Playground Manifest Reference

A playground manifest is a single YAML document. At the top level:

kind: playground          # always "playground"
name: my-playground       # unique name (also the URL slug)
base: flexbox             # the base playground (informational in dumps;
                          # on create, the base is set via --base)
title: My Playground
description: A one-paragraph summary shown on the playground card.
categories:
  - linux
markdown: |
  The long-form landing page body (markdown).
cover: https://...        # cover image URL (uploaded via the UI)
playground:
  networks: [...]         # see Networks
  machines: [...]         # see Machines
  tabs: [...]             # see Tabs
  initTasks: {...}        # see Init tasks
  initConditions: {...}   # see Init tasks
  registryAuth: user:pass # see Access control & registry
  accessControl: {...}    # see Access control & registry

The two commands that consume manifests have different expectations:

• create -f accepts a partial spec: networks, tabs, categories, and resources are inherited from the base when omitted. Still required: title, a non-empty accessControl (all three lists), and for every machine - name, users, drives, and network.
• update -f expects a complete manifest: networks, tabs, categories, and accessControl must all be present. The reliable workflow is to dump the current manifest with labctl playground manifest, edit it, and submit the result.

Working with manifests

# List available bases and your own playgrounds:
labctl playground catalog --filter base
labctl playground catalog --filter my-custom

# Create (--base is mandatory; -f is optional - without it you get a clone of the base):
labctl playground create <name> --base <base> [-f manifest.yaml]

# Dump the current (effective) manifest of a playground:
labctl playground manifest <name>

# Apply an updated manifest:
labctl playground update <name> -f manifest.yaml

# Start / stop / remove:
labctl playground start <name> [--open] [--ide] [--ssh] [-i key=value]
labctl playground stop <playground-instance-id>
labctl playground remove <name>

Both create and update accept -f - to read the manifest from stdin - convenient for heredocs and pipelines.

playground.machines is a list of VM definitions (1 to 5 machines per playground):

  machines:
    - name: dev-01
      backend: firecracker
      kernel:
        source: "6.1"
      users:
        - name: laborant
          default: true
          welcome: |
            Hello there!
      drives:
        - source: ubuntu-24-04
          mount: /
          size: 10GiB
      network:
        interfaces:
          - network: local
      resources:
        cpuCount: 2
        ramSize: 2GiB
      startupFiles:
        - path: /home/laborant/.bashrc
          append: true
          content: |
            alias k=kubectl
      noSSH: false

Users

root is always available, even if not listed.

Drives

Drives map to devices in list order: /dev/vda, /dev/vdb, ... Up to 24 drives per machine. (You may also see source: snapshot with a snapshot object in dumped manifests - that's how playgrounds saved from a stopped instance reference their drive snapshots; these entries are platform-generated, not hand-written.)

Resources

Per-VM and per-playground totals are capped by your plan (free tier: 2 vCPU / 4 GiB per VM, 5 vCPU / 8 GiB per playground; paid plans: 4 vCPU / 10 GiB per VM, 10 vCPU / 16 GiB per playground). Requests exceeding the budget are scaled down proportionally rather than rejected.

Startup files

Up to 10 startup files per machine.

playground.networks declares the isolated bridge networks of the playground; machines join them via network.interfaces:

  networks:
    - name: frontend
      subnet: 10.0.1.0/24
    - name: backend
      subnet: 10.0.2.0/24
      gateway: 10.0.2.254
      private: true

  machines:
    - name: web-01
      network:
        interfaces:
          - network: frontend
            address: 10.0.1.10
          - network: backend       # address auto-assigned

Network fields

A playground has at least one network; when the manifest defines none, the base's default network is used (conventionally local, 172.16.0.0/24). Networks are isolated from each other - inter-network traffic flows only through machines attached to both.

Interface fields

Interfaces appear in the VM in list order as eth0, eth1, ... The machine's default route goes via the first non-private network among its interfaces. Machines resolve each other by machine name and by <machine>.<network> names.

playground.tabs defines the panes of the playground page (1-10 entries). Omitting it yields the defaults (an IDE tab for most base playgrounds + a terminal per SSH-enabled machine, plus the Kubernetes Explorer for Kubernetes playgrounds); defining it replaces the defaults entirely:

  tabs:
    - kind: ide
    - kind: http-port
      name: Web UI
      machine: dev-01
      number: 8080
    - kind: terminal
      machine: dev-01
    - kind: web-page
      name: Docs
      url: https://example.com/docs

A bare - machine: <name> entry is shorthand for a terminal tab on that machine.

playground.initTasks is a map of named provisioning tasks executed inside the machines during startup (see the init tasks lesson for a guided tour):

  initTasks:
    init_install_tools:
      init: true
      machine: dev-01
      user: root
      timeout_seconds: 120
      run: |
        apt-get update && apt-get install -y jq

    init_seed_data:
      init: true
      machine: dev-01
      user: laborant
      needs:
        - init_install_tools
      run: |
        mkdir -p ~/data && echo hello > ~/data/seed.txt

Init conditions

playground.initConditions declares start-time parameters that users provide in the UI or via labctl playground start -i key=value:

  initConditions:
    values:
      - key: k8s_flavor
        default: k3s
        options: [k3s, kubeadm]
      - key: repo_url
        default: ""
        nullable: true
        placeholder: https://github.com/you/repo
        validationRegex: "^https://.*$"

Access control

playground.accessControl holds three lists of principals (see Sharing and Access Control for recipes):

  accessControl:
    canList:
      - anyone
    canRead:
      - anyone
    canStart:
      - owner

Principals include owner, anyone, authenticated, user:<...>, and student:<training-name>; the full vocabulary is documented in How to Control Access to Your Content. When a manifest is submitted via labctl, all three lists must be present and non-empty; playgrounds cloned without a manifest inherit the access settings of their base (official bases are public).

Older manifests may contain a deprecated access: {mode: private|public} block - labctl transparently converts it to the equivalent accessControl on update.

Registry auth

Every playground comes with a built-in container registry reachable from inside the VMs at registry.iximiuz.com. By default it's unauthenticated (but only accessible from within the playground); registryAuth puts it behind credentials:

  registryAuth: someuser:somepassword

This is handy for practicing docker login flows and private-registry scenarios without leaving the sandbox.