Skip to content

Setting Up

You will use a GitHub Codespace to author and validate sandboxes entirely in your browser with the same pinned 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 Content repository planning and validation.
sandbox Sandbox scaffolding, preview, build, test, and shell access.

Start a Codespace

  1. Open the content 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 content repository commands.

Confirm your tools

Run a quick smoke check from the content repository root:

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

Ready when

Each command completes without errors.

If commands are missing

Start a Devbox shell, then try again:

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

Check the Sandbox CLI version

Independent sandbox attach terminals require v1.25+, the current Bashp MCP tools require v1.26+, and all-VM background live reload requires v1.27+. Devbox/Nix pins can lag behind the latest release: use the repository's toolchain upgrade process for managed installations. See CLI version requirements and updating the CLI.

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 content repository 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 content repository validation.
skills validate . 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.

Use the coding agent

OMP is the coding agent configured to help you author and validate content in the repository.

Start OMP from the content repository root:

@codespace-author ➜ .../quickstart (main)
omp

Codespaces signs you into GitHub Copilot automatically. On a workstation, start omp and complete the login flow when prompted.

Stage your finished changes and create a signed-off commit:

@codespace-author ➜ .../quickstart (main)
git add items/hello-image
lgit -s

lgit generates the conventional commit message from your staged changes. The coding-agent harness never pushes, so review the local commit and push it yourself outside the agent session.

Read the Content Repository Harness guide for the agent's authoring skills and enforced safeguards.

The Bashp MCP server provides bashp_find, bashp_explain, and bashp_resolve for agent-assisted lifecycle authoring. Configure the MCP client to start sandbox mcp in the content repository. These read-only tools inspect source and dependencies; their results do not replace lint, content validation, or sandbox test.

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 content repository 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.