sandbox.yaml¶

sandbox.yaml defines your sandbox: the virtual machines, the tools in the UI, and how they connect.

All field names are camelCase — not snake_case.

Minimal working example¶

apiVersion: p3.ed.linuxfoundation.org/v1alpha1
kind: SandboxBlueprint
metadata:
  name: my-sandbox
spec:
  virtualmachines:
    - name: host1
      baseImage: ubuntu
  tools:
    - name: terminal
      terminal:
        version: v1
        targetHost: host1
        targetUser: tux
    - name: instructions
      instructions:
        version: v1
        sourcePath: task.en.md
  ui:
    version: v1
    defaultTool: terminal
    showTimer: false

Virtual machines¶

spec:
  virtualmachines:
    - name: host1
      baseImage: ubuntu
      ports:
        - "*"
      resources:
        requests:
          memory: "2Gi"
          cpu: "1"
        limits:
          memory: "4Gi"
          storage: "10Gi"

Field	Required	Default	Description
`name`	Yes	—	VM hostname. Lowercase alphanumeric and hyphens only.
`baseImage`	Yes	—	Image shorthand or full URL. See base images.
`user`	No	`tux`	Primary user account on the VM.
`ports`	No	`["*"]`	Ports to expose. Single (`"80"`), range (`"8000-8080"`), or `"*"` for all.
`resources`	No	—	CPU and memory allocation.

Resources¶

resources:
  requests:
    memory: "2Gi" # minimum
    cpu: "1"
  limits:
    memory: "4Gi" # maximum
    storage: "10Gi" # overlay disk size

Memory and storage use binary units: Mi, Gi. CPU uses cores ("1", "2.5") or millicores ("500m").

Tools¶

Each tool entry requires a name and exactly one tool type block.

Terminal¶

- name: terminal
  terminal:
    version: v1
    targetHost: host1
    targetUser: student

Field	Required	Description
`version`	Yes	Always `v1`.
`targetHost`	Yes	VM to connect to. Must match a VM `name`.
`targetUser`	Yes	User to connect as.

Warning

The field is targetHost — not target, not host. Validation will fail silently with the wrong name.

For multi-VM sandboxes, add one terminal per VM:

- name: cp-terminal
  terminal:
    version: v1
    targetHost: cp
    targetUser: student
- name: worker-terminal
  terminal:
    version: v1
    targetHost: worker
    targetUser: student

IDE¶

- name: editor
  ide:
    version: v1
    targetHost: host1
    targetUser: student
    workspaceDir: /home/student/project

Field	Required	Description
`version`	Yes	Always `v1`.
`targetHost`	Yes	VM to connect to via SSHFS.
`targetUser`	Yes	User for the SSHFS connection.
`workspaceDir`	No	Directory to open. Defaults to the user's home directory.

Browser¶

- name: browser
  browser:
    version: v1
    startingURL: "http://host1:8080"
    kioskMode: true

Field	Required	Description
`version`	Yes	Always `v1`.
`startingURL`	Yes	URL to open on launch. Use the VM `name` as the hostname (e.g. `http://host1:8080`).
`kioskMode`	No	Hide the browser toolbar. Defaults to `false`.

Instructions¶

- name: instructions
  instructions:
    version: v1
    sourcePath: task.en.md

Field	Required	Description
`version`	Yes	Always `v1`.
`sourcePath`	Yes	Path to the markdown file, relative to the sandbox root.

UI¶

ui:
  version: v1
  defaultTool: terminal
  showTimer: false

Field	Required	Description
`version`	Yes	Always `v1`.
`defaultTool`	Yes	Tool shown when the sandbox opens. Must exactly match a tool `name`.
`showTimer`	No	Show a countdown timer. Required `true` for labs. Defaults to `true`.

TTL¶

spec:
  ttlSeconds: 3600

How long the sandbox runs before automatic teardown. Defaults to 3600 (1 hour). Maximum is 86400 (24 hours). Not enforced during local development with sandbox shell.

Base images¶

Write a shorthand name in baseImage — the CLI resolves it to ghcr.io/lf-certification/sandbox-vm-<name> automatically. Use the full image URL only when referencing an image outside this registry.

`baseImage`	OS	Pre-installed
`ubuntu`	Ubuntu 24.04 (noble)	—
`debian`	Debian 13 (trixie)	—
`k3s`	Debian 13 (trixie)	K3s 1.35.2
`k8s`	Debian 13 (trixie)	Kubernetes 1.35.2
`k8sn`	Debian 13 (trixie)	Kubernetes 1.35.2, nerdctl

Multi-VM example¶

A three-node Kubernetes cluster with a terminal for each node:

apiVersion: p3.ed.linuxfoundation.org/v1alpha1
kind: SandboxBlueprint
metadata:
  name: kubernetes-lab
spec:
  ttlSeconds: 7200
  virtualmachines:
    - name: cp
      baseImage: k8sn
      ports:
        - "6443"
        - "2379-2380"
        - "10250"
      resources:
        requests:
          memory: "2Gi"
    - name: worker
      baseImage: k8sn
      ports:
        - "10250"
        - "30000-32767"
      resources:
        requests:
          memory: "2Gi"
  tools:
    - name: cp
      terminal:
        version: v1
        targetHost: cp
        targetUser: tux
    - name: worker
      terminal:
        version: v1
        targetHost: worker
        targetUser: tux
    - name: instructions
      instructions:
        version: v1
        sourcePath: instructions.md
  ui:
    version: v1
    defaultTool: cp
    showTimer: true