Skip to content

Setting Up

Cartridge repositories are pre-configured for GitHub Codespaces. You can author and validate sandboxes entirely in your browser, with the same skills and sandbox tools used by CI.

What setup gives you

Tool Why you need it
Codespaces Browser-based editor, terminal, and VM support.
Devbox Reproducible command-line toolchain.
skills Cartridge planning and validation.
sandbox Sandbox scaffolding, preview, build, test, and shell access.

Start a Codespace

  1. Open the cartridge repository in GitHub.
  2. Click Code.
  3. Open the Codespaces tab.
  4. Click Create codespace on main.
  5. Wait for the terminal setup to finish.

Wait for setup to complete

The first start installs the Devbox toolchain and repository hooks. Wait until the terminal returns to a prompt before running cartridge commands.

Confirm your tools

Run a quick smoke check from the cartridge root:

@codespace-author ➜ .../quickstart (main)
skills --help
sandbox --help

Ready when

Both commands print help output without errors.

If commands are missing

Start a Devbox shell, then try again:

@codespace-author ➜ .../quickstart (main)
devbox shell

Know the common commands

@codespace-author ➜ .../quickstart (main)
skills plan .
skills validate --full .
Command Purpose
skills plan . Shows the per-competency item prescription from blueprint.yaml.
skills validate --full . Runs full SkillCred cartridge validation.
sandbox instructions Previews candidate instructions from inside an item directory.
sandbox test Runs build, setup, score, answer, and score again for one sandbox.
@codespace-author ➜ .../quickstart (main)
make validate
Command Purpose
make validate Runs lab cartridge validation.
skills validate --product lab . Runs the same lab validation directly.
sandbox instructions Previews learner instructions from inside a lab directory.
sandbox test Runs build, setup, score, answer, and score again for one sandbox.

Preview instructions

From inside a sandbox directory, run:

@codespace-author ➜ .../items/hello-image (main)
sandbox instructions

Preview server started

The port may differ in your environment. Open the localhost URL shown in your terminal.

terminal output
ghcr.io/lf-certification/p3-sandbox-instructions-generator:latest
Building instructions...
Starting preview server at http://127.0.0.1:<port>

Keep preview running

Leave the preview running while you edit task.en.md or instructions.md. The browser updates automatically when the file changes.

Troubleshooting

The preview URL does not open

Open the Ports tab in Codespaces and look for the forwarded localhost port. If it is not open, copy the forwarded URL from the Ports tab.

skills or sandbox is not found

Run devbox shell from the cartridge root. If that still fails, run devbox install and open a new terminal.

A sandbox VM does not start

Wait for the Codespace to finish initializing, then retry. Sandbox VMs need the devcontainer's VM support and can take longer on first build.

Next step

You are ready to build. Continue with the Quickstart.