# 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](https://skills.staging.lf-cert.cloud/docs/sandbox/cli/#version-requirements) and [updating the CLI](https://skills.staging.lf-cert.cloud/docs/sandbox/cli/#sandbox-update).

## Know the common commands

**SkillCred content repository**

**@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. |

**Lab content repository**

**@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](https://github.com/LF-Certification/skills-platform/blob/main/omp-extensions/content-repo-harness/README.md) for the agent's authoring skills and enforced safeguards.

The [Bashp MCP server](https://skills.staging.lf-cert.cloud/docs/sandbox/cli/#sandbox-mcp) 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](https://skills.staging.lf-cert.cloud/docs/quickstart/index.md).