Run a Labspace (instructions on the left, VS Code on the right, Docker available to the learner) with sbx run instead of a six-container docker compose up. See docs/architecture.md for diagrams of both setups.
This repository publishes three kits to GitHub Container Registry. Each has its own README with its run command and the ports to pin:
| Kit | Package | README |
|---|---|---|
| Labspace runtime: the interface, VS Code and a private Docker engine | ghcr.io/mathieu-benoit/labsbxes/labspace |
kit/README.md |
| Hello Labspace: a minimal lab (content kit) | ghcr.io/mathieu-benoit/labsbxes/hello-lab |
examples/hello-lab/README.md |
| Building Container Images: Best Practices (content kit) | ghcr.io/mathieu-benoit/labsbxes/building-images-lab |
examples/building-images-lab/README.md |
A content kit always runs with the Labspace kit. Commands for all three are in Published kits.
The infrastructure is a single Sandbox Kit (v3 mixin) that layers onto the built-in shell agent.
sbx run shell --kit ./kit -p 8085:8085 -p 3000:3000 --name my-lab ./examples/hello-lab
sbx ports my-labThen open the interface: http://127.0.0.1:<HOST PORT>/, with the host port sbx ports lists for sandbox port 3030.
./examples/hello-labis the content repo, mounted as the sandbox workspace. It has the same layout as any labspace-infra content repo:labspace/(labspace.yaml+ markdown) andproject/(what the IDE opens).- The kit publishes its ports itself (see Ports).
-ponly pins a host port where something expects a fixedlocalhostaddress:-p 8085:8085is required: the interface embeds the IDE athttp://localhost:8085.-p 3000:3000is for hello-lab's tab link tohttp://localhost:3000. A lab with no such link doesn't need it.-p 3030:3030is optional: add it to always open the interface at http://localhost:3030.
- If host port 8085 is already taken (for example by a running Compose Labspace), the IDE panel won't load: only one lab at a time can use it.
- The command attaches you to a bash session in the sandbox. Add
-dto start it detached; the kit declareslong-running@1, so the lab keeps running either way. - Re-attach with
sbx run --name my-lab, stop withsbx stop my-lab, throw everything away withsbx rm my-lab.
The kit declares the ports the sandbox serves with the port@1 capability (3030, 8085 and appPort), so they are published as soon as the sandbox is created, with no sbx ports command. A kit only names the sandbox port. The host port is chosen by sbx: a free one on 127.0.0.1, chosen again at every start. The spec forbids a kit from pinning it, so that two shared kits can't ask for the same one. When the host port matters, you pin it yourself with -p (or sbx ports --publish).
graph LR
You(["Learner, in a browser"])
subgraph Host["Host machine"]
direction TB
Pinned["localhost:8085, :3000<br/>you pin them with -p"]
Ephemeral["127.0.0.1:random ports<br/>sbx chooses them"]
end
subgraph Sandbox["Docker Sandbox"]
direction TB
Services["interface :3030<br/>code-server :8085<br/>learner app :appPort"]
end
Kit["Labspace kit: 3 x port@1"]
You -->|opens the interface| Ephemeral
You -->|"IDE panel, tab links"| Pinned
Kit -->|"published at sbx create"| Ephemeral
Pinned -->|"sbx run -p"| Services
Ephemeral -->|forwards to| Services
%% Styles — containers
style Host fill:#E5F2FC,stroke:#1D63ED,color:#00084D
style Sandbox fill:#f0faf4,stroke:#86c5a0,color:#00084D
%% Styles — host nodes
style Pinned fill:#E5F2FC,stroke:#1D63ED,color:#00084D
style Ephemeral fill:#E5F2FC,stroke:#1D63ED,color:#00084D
%% Styles — kit
style Kit fill:#fff,stroke:#0DB7ED,color:#384D54
%% Styles — sandbox nodes
style Services fill:#e0f2e6,stroke:#6db88a,color:#384D54
%% Styles — actor
style You fill:#fff,stroke:#1D63ED,color:#00084D
sbx ports my-lab lists what sbx picked (for example 127.0.0.1:60036 -> 3030). The interface works from there, but its IDE panel loads http://localhost:8085, a fixed address, which is why every command here pins 8085. Without it the panel stays blank.
Launching the kit with no lab (an empty folder, no content kit) does not fail. It shows a built-in getting-started lab: what happened, the folder it looked in, and the three ways to give the sandbox a lab (a local folder, a content kit, a set), with a "Save" scaffold that writes a starter lab (labspace/, project/, and the two content-kit files) into the IDE. Copy it out with sbx cp <sandbox>:/home/agent/project/my-lab ./my-lab, then run it with --kit ./kit --kit ./my-lab. The content is in kit/files/opt/labspace/default-content.
The lab is chosen at every boot, first match wins: the workspace's labspace/labspace.yaml, then a content kit, then the built-in lab.
Running a lab from a workspace folder is for authoring and demos. To hand a lab to someone, package its content as a second kit. It carries only the two folders and composes with the Labspace kit:
# from the repo root; the lab content comes from the kit, not from the workspace
sbx run shell --kit ./kit --kit ./examples/hello-lab -p 8085:8085 -p 3000:3000 --name hello-labexamples/hello-lab is both a content repo and a content kit: hello-lab.yaml (a mixin that requires the Labspace kit and provides labspace-content) and hello-lab.dockerfile (FROM scratch, copies labspace/ and project/ to /opt/labspace/content). To make your own lab a kit, add those two files to its repo, adjusting the name and version. If the lab runs an app the learner opens, declare its port in the content kit with port@1, as hello-lab does for 3000: the lab then publishes what it needs whatever appPort is set to, and two kits declaring the same port are a single publication.
When the content comes from a kit, the instructions are read from the kit, and project/ is copied once to ~/project in the sandbox, which is what the IDE opens. The learner's edits stay in the sandbox and survive sbx stop/sbx run; they are not written to the host. If the workspace itself contains a labspace/labspace.yaml, that wins over the kit, which is what makes authoring against a published kit possible.
The resolver enforces the pairing: the content kit alone fails with requires "labspace >= 0.1.0" but nothing in the set provides it, and two content kits conflict because both provide labspace-content.
A kind: set merges the two into one published kit. Publish both kits to a registry, then publish the set that lists them (set members must be registry references; local paths are refused):
# hello-lab-set.yaml
# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: set
displayName: Hello Labspace (ready to run)
version: "0.1.10"
kits:
- ref: docker.io/<you>/labspace:0.1.10
- ref: docker.io/<you>/hello-lab:0.1.10docker buildx build --builder kit-builder kit -f kit/labspace.yaml -t docker.io/<you>/labspace:0.1.10 --push
docker buildx build --builder kit-builder examples/hello-lab -f examples/hello-lab/hello-lab.yaml -t docker.io/<you>/hello-lab:0.1.10 --push
docker buildx build --builder kit-builder . -f hello-lab-set.yaml -t docker.io/<you>/hello-lab-set:0.1.10 --push
# learners:
sbx run shell --kit docker.io/<you>/hello-lab-set:0.1.10 -p 8085:8085 -p 3000:3000 --name hello-labkit-builder is a docker-container builder (docker buildx create --name kit-builder --driver docker-container --bootstrap), as in the spec README.
The published set is one ordinary mixin that pins both members by digest and carries the merged capabilities and hooks. By default sbx only installs kits from docker.io/ and dhi.io/ (kit.allowedSources).
.github/workflows/publish-kits.yaml builds the kits for linux/amd64 and linux/arm64 and publishes them to this repository's container registry:
| Kit | Reference | Source |
|---|---|---|
| Labspace runtime | ghcr.io/mathieu-benoit/labsbxes/labspace |
kit/ |
hello-lab content |
ghcr.io/mathieu-benoit/labsbxes/hello-lab |
examples/hello-lab/ |
building-images-lab content |
ghcr.io/mathieu-benoit/labsbxes/building-images-lab |
examples/building-images-lab/ |
Run them from a dedicated, empty folder. sbx run mounts the current folder into the sandbox as its workspace, read-write. Started from your home directory, that would hand the sandbox your SSH keys, cloud and registry credentials, shell history and every other project, which defeats the point of a sandbox. Give it only what the lab needs: with a content kit the lab doesn't use the workspace at all, so an empty folder is enough. (sbx also blocks the home directory outright, with mount "/Users/<you>" overlaps Sandboxes configuration, state or credentials.)
mkdir -p ~/sbx-lab && cd ~/sbx-labThen start one of the labs from that folder.
The built-in getting-started lab (Labspace kit only):
sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.10 -p 8085:8085 --name labspacehello-lab (pin 3000 for its tab link):
sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.10 --kit ghcr.io/mathieu-benoit/labsbxes/hello-lab:0.1.10 -p 8085:8085 -p 3000:3000 --name hello-labbuilding-images-lab (pin 5050 for its Quote App tab):
sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.10 --kit ghcr.io/mathieu-benoit/labsbxes/building-images-lab:0.1.10 -p 8085:8085 -p 5050:5050 --name building-images-labThen open the host port sbx ports <name> lists for sandbox port 3030 (for example sbx ports hello-lab). That host port is picked by sbx and changes at every start; add -p 3030:3030 to any of these commands to open the interface at http://localhost:3030 instead.
| Event | What it does |
|---|---|
| Pull request | Builds all kits to a local OCI layout and validates them with kit-tck; pushes nothing. |
Push of a v* tag |
Publishes :<version from the kit's descriptor> and :latest. A version that already exists is skipped, so a published version is immutable. |
Manual run (Actions → publish-kits → Run workflow) on main |
Publishes :edge and :sha-<short>. On any other branch it only builds. |
Commits to main don't publish anything on their own.
The kits are versioned in lockstep. To release, bump version: to the same value in every descriptor (kit/labspace.yaml, examples/hello-lab/hello-lab.yaml, examples/building-images-lab/building-images-lab.yaml), merge, then push the matching tag (git tag v0.2.0 && git push origin v0.2.0). The workflow's first job fails the run if the versions differ, or if the tag doesn't name them (v0.2.0 must mean 0.2.0). The v is only on the git tag; the published image tags have none (:0.2.0), as the kit spec requires.
The workflow runs kit-tck validate (the specification's conformance checker, pinned and checksum-verified) every time: on pull requests against the built OCI layout, and after each publish against the artifact that actually reached the registry. The descriptors' sourceUrl becomes the org.opencontainers.image.source annotation, which is what links the packages to this repository.
By default sbx only installs kits from docker.io/ and dhi.io/ (kit.allowedSources). To use these references, allow the namespace:
sbx settings set kit.allowedSources '["docker.io/","dhi.io/","ghcr.io/mathieu-benoit/"]'New GHCR packages can start out private. After the first publish, check each package's visibility under the repository's Packages and make it public if learners should be able to pull it without signing in.
.github/workflows/publish-pages.yaml publishes a landing page at https://mathieu-benoit.github.io/labsbxes/ on every v* tag (or on a manual run): a blade per kit, each opening a rendering of that kit's README. The blades it lists, with their titles, icons and chips, are in site/kits.json: one per kit, plus a page on what's different from labspace-infra (site/pages/compare.html). site/build.sh assembles the site, and on a release the README links point to the tag and the page shows its version.
To preview it locally:
bash site/build.sh /tmp/labsbxes-site main && python3 -m http.server 8000 --directory /tmp/labsbxes-siteOne-time setup: under Settings → Pages, set the source to GitHub Actions. Then under Settings → Environments → github-pages, add a deployment tag rule for v*, so that release tags are allowed to deploy (by default only the default branch can).
docs/architecture.md has a diagram of each setup and a side-by-side summary.
| labspace-infra (Compose) | This kit | Why |
|---|---|---|
socket-proxy |
Removed | The sandbox is a microVM with its own Docker engine (dockerd@1). The learner's docker never reaches the host engine, so there is nothing to filter, label, allowlist or remap. Bind mounts of the project folder just work, since the engine and the files share a filesystem. |
workspace-cleaner |
Removed | The engine store lives in the sandbox. sbx rm deletes every container, volume, network and image the lab created. |
host-port-republisher |
Removed | Its job was bridging "container publishes a port" to "localhost on the host". Ports are now published by the runtime (port@1, sbx ports). |
configurator |
Replaced by two small scripts | labspace-init.sh (once: keypair, dirs) and labspace-stage.sh (every boot: copy labspace/ to the instructions dir, write metadata). No git clone, no tarball, no volumes: the content is the workspace, or a content kit. |
interface |
Kept, unchanged | Reused from the published dockersamples/labspace-interface image (pinned to labspace-infra v0.33.0 by digest in labspace.dockerfile), copied into the overlay at build time. The built-in shell kit (Debian 13) has no Node, so the overlay also carries the node binary from node:24-bookworm-slim. |
workspace (code-server) |
Kept, built into the overlay | Same approach as the code-server kit in sbx-kits-contrib: pinned install at build time, no download at create. |
support-vscode-extension |
Kept, unchanged | Reused from dockersamples/labspace-support-vscode-extension. The JWT + unix socket between interface and IDE still works, now between two processes in one sandbox. |
marlin-mock (development stack only) |
Removed | Analytics are off (analytics_enabled: false). |
5 named volumes, 1 network, 5 configs |
None |
Net: the 6 containers and 5 volumes of compose.run.yaml become 2 processes (node, code-server) plus the sandbox's own engine.
kit/
labspace.yaml # descriptor: kind mixin, capabilities, lifecycle hooks
labspace.dockerfile # builds the overlay (FROM scratch at the end)
files/
opt/labspace/bin/ # labspace-init.sh, labspace-stage.sh, labspace-ide.sh, labspace-ui.sh
home/agent/.local/share/code-server/User/settings.json
examples/hello-lab/ # a tiny lab: a content repo, and (hello-lab.yaml/.dockerfile) a content kit
examples/building-images-lab/ # dockersamples/labspace-building-images as a content kit (Quote App on 5050)
site/ # the GitHub Pages landing page: kits.json, build.sh, index.html, app.js, style.css, pages/
- Create (once):
labspace-init.sh(root) makes/etc/labspace-support/*and an ES256 keypair. - Every boot: the runtime starts the sandbox's Docker engine, then runs the startup hooks in order:
labspace-stage.shpicks the content (<workspace>/labspace/labspace.yamlif present, else a content kit's/opt/labspace/content), warns with the fix and stops if there is neither, stages the instructions, records the project folder in/labspace/project-dir, and writes the metadata the interface reads.labspace-ide.sh(background) starts code-server on:8085, opened on that project folder.labspace-ui.sh(background) starts the interface on:3030.
- Run button: the browser sends a code block index, the interface reads the command from the markdown on disk, signs a 15 s JWT and POSTs it to the extension's unix socket, and the extension types it in the IDE terminal. Unchanged from labspace-infra.
Logs: sbx exec my-lab -- cat /tmp/labspace-ui.log /tmp/labspace-ide.log.
| Arg | Default | Meaning |
|---|---|---|
devMode |
false |
--kit-arg devMode=true reads <workspace>/labspace live, so editing a markdown file on the host and reloading the page is enough. |
appPort |
3000 |
Extra port published for an app the learner runs, on a random host port (sbx ports <name>). For lab links such as :tabLink{href="http://localhost:3000"} to work, also pin it: -p 3000:3000. --kit-arg appPort=8080 changes the port. |
codeServerVersion |
4.140.0 |
Build-time pin. |
Egress is limited to Docker Hub (for image pulls) and the Open VSX marketplace. A lab that needs more declares it in its own network policy (sbx policy), or in a content kit.
Tested with sbx 0.53 on Windows, using examples/hello-lab:
| Checked | Result |
|---|---|
| Build through the kit frontend (descriptor validation included) | Pass |
sbx run shell --kit ./kit -d ... creates the sandbox, install hook and 3 startup hooks run |
Pass |
Interface serves the lab (/api/labspace returns the title and sections) |
Pass |
code-server answers and opens <workspace>/project; support extension activates and creates its socket |
Pass |
Run button path: POST .../command → JWT → unix socket → command typed in the IDE terminal |
Pass |
Private Docker engine inside the sandbox (docker info) |
Pass |
port@1 publishing (appPort 3000 → ephemeral host port; 3030/8085 pinned with -p) |
Pass |
Fresh sandbox with no -p: 3030, 8085 and 3000 are published at create on ephemeral 127.0.0.1 ports (60023, 60024, 60025), the interface answers on its port, and sbx stop then sbx run --name gives new ones (60026, 60027, 60028) |
Pass |
The name labels set on the port@1 entries in sbx ports |
Not shown by sbx 0.53 |
Only -p 8085:8085 pinned: the interface opened on its ephemeral port (127.0.0.1:60036), the IDE panel loaded from localhost:8085, and Run typed the command into the IDE terminal |
Pass |
Content kit declaring its own port@1 (hello-lab, 3000): sbx kit inspect reports Published: 1 ports; with --kit-arg appPort=8080 both 8080 and 3000 are published, and nginx started on 3000 answers on its ephemeral host port; with the default appPort the two 3000 entries are one publication |
Pass |
docker pull / docker run -p 3000:80 nginx:alpine inside the sandbox, reached from the host through the appPort binding |
Pass |
IDE embedded in the interface at localhost:8085 (split view), with Run, Save and the open-file link clicked in the real UI |
Pass |
devMode=true: a markdown edit on the host shows up in the interface without a restart |
Pass |
sbx stop then sbx run --name ... -d: services come back, hooks re-run cleanly, pulled images are still there |
Pass |
Workspace without labspace/labspace.yaml: startup warns with the fix, sandbox still starts |
Pass |
| Running the same kit twice on one host, ports pinned to non-default values (3031/8086) | Pass for the interface and IDE; the embedded IDE panel only loads on 8085 |
Infra kit + content kit from an empty folder: lab served from the kit, ~/project seeded, IDE opens it, Docker works |
Pass |
Learner edits in ~/project survive sbx stop / sbx run --name (project is copied only once) |
Pass |
Content kit alone is refused at resolution (requires labspace) |
Pass |
| No content at all: the built-in getting-started lab is served, placeholders filled (workspace path, sandbox name), IDE opens the scratch project, no failed hook | Pass |
Built-in lab's Save scaffold writes the 5 starter files; sbx cp copies them out; the copy runs as a content kit and serves "My lab" |
Pass |
| Workspace content still wins over the other two sources | Pass |
| Before the built-in lab: no content meant a failed startup hook, nothing listening and a blank browser | (the reason it exists) |
kind: set built from both kits and pushed to a local registry: merged descriptor is a mixin, provides the union, members pinned by digest, 1 install + 3 startup hooks |
Pass (descriptor inspected) |
| Running the lab from the set reference | Not tested: the sandbox runtime refused localhost:5000/... because kit.allowedSources only allows docker.io/ and dhi.io/ |
Two content kits composed together is refused; content kit baked into the set while the workspace has its own labspace/ |
Not tested |
macOS / Linux hosts, --cloud sandboxes, content bigger than the sample |
Not tested |
The kit declares network-policy@1 (Docker Hub for image pulls, Open VSX for extensions). Under a managed governance policy with default-deny, those rules were not applied and docker pull failed with 403 Forbidden from registry-1.docker.io (sbx policy log <name> shows what was blocked). With governance out of the way, sbx policy ls shows them as a kit-sourced policy scoped to the sandbox ("managed by a kit; recreated at sandbox create"), and pulls work. If pulls fail on your machine, check sbx policy log <name> and sbx policy ls <name>.
- One port for everything. Today the learner must pin
-p 8085:8085because the interface hard-codeshttp://localhost:8085for the IDE. A gateway (or anIDE_URLsetting in the interface) serving the IDE under the interface's own port would reduce this to one published port, and could let the kit work with ephemeral ports. - Instructions are no longer protected from the learner. In labspace-infra the interface mounted them read-only. In a sandbox the agent user owns the VM anyway, so this was dropped.
- A set is a pinned artifact. Bumping the Labspace kit means republishing every lab set that includes it. Keeping the content kit separate (and composing with
--kit) avoids that, at the cost of two references. - Kit content is not on the host. With a content kit, the learner's project lives in the sandbox (
~/project), so it is gone aftersbx rm. Mount a host folder if it must be kept. - The first run still mounts the current directory as the workspace (the default for
sbx run). Run from a dedicated, empty folder when using a content kit, never from your home directory: whatever folder you start in is exposed to the sandbox. - Init scripts. labspace-infra ran
/init-scripts/*in the configurator. The equivalent here would be running an optional<workspace>/labspace/init.shin the install hook. - The
ttydworkspace mode in the interface (WORKSPACE_TYPE=ttyd) shows the interface already supports a non-VS-Code terminal backend; not used here.