# Cleanroom

> Use when an agent should bake a repository into a warm SporeVM snapshot with cleanroom, validate or author cleanroom.yaml policy, verify a spore's provenance, or serve the credential-mediation gateway for baked spores.

- Skill: `buildkite/cleanroom` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add buildkite/cleanroom`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buildkite/cleanroom/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: buildkite (https://skillmd.com/u/buildkite)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/buildkite/cleanroom

---


# Cleanroom

Cleanroom is a thin layer over [SporeVM](https://github.com/sporevm/sporevm):
it compiles repository policy into enforceable spore configuration, bakes a
warm `.spore` snapshot with dependencies installed, attaches checkable
provenance, and mediates credentials into running spores via a host-side
gateway. Cleanroom is the build tool; `spore` is the run tool. This skill
assumes both `cleanroom` and `spore` are installed.

## Start Here

1. Confirm the CLI is available with `cleanroom version` when install state
   matters. If flag availability is unclear, run `cleanroom <command> --help`
   before guessing.
2. Inspect policy before expensive work. Cleanroom reads `cleanroom.yaml`,
   then `.buildkite/cleanroom.yaml`:

```bash
cleanroom policy validate
cleanroom policy validate --chdir <path>   # validate another directory
cleanroom policy validate --json           # machine-readable
```

## Bake And Run

Bake a repository into a warm spore, then run work from it with spore:

```bash
cleanroom bake . --out repo.spore
spore run --from repo.spore 'make test'
```

- Dependencies install during bake via `sandbox.warmup` policy commands, so
  restores are fast and repeatable.
- Rebaking with an unchanged policy and commit is a no-op; a dirty worktree
  always rebakes and records `workspace.git.dirty=true`.
- Fan out copy-on-write children that share the parent's memory and disk:

```bash
spore fork repo.spore --count 10 --out agents/
```

## Verify Provenance

Check what produced an artifact and what it needs to run:

```bash
cleanroom verify repo.spore                  # provenance facts and run hint
cleanroom verify repo.spore --dir .          # audit bake key against the repo
spore --json inspect repo.spore | cleanroom verify   # from inspect output
```

Verify fails closed on missing or malformed provenance. The `--dir` audit is
an integrity check, not proof of origin: the bake key is a public hash, so a
match shows the artifact is consistent with the repository's current policy
and commit — it cannot prove who baked it.

## Mediated Credentials

When policy requests `sandbox.mediation.services`, the spore reaches
credentials only through a host-side gateway; secrets never enter the guest
or its captured artifact:

```bash
cleanroom gateway serve --dir . --for repo.spore --socket gw.sock &
spore run --from repo.spore --bind-service cleanroom-gateway:8170=unix:gw.sock 'COMMAND'
```

`--dir` is the trust root: grants resolve from the repository's own policy
and git facts. `--for` audits the spore's bake key against the repository and
refuses to serve on mismatch — but the key is public, so passing the audit is
not proof the spore was baked by you. The authorization boundary is the bind:
only bind the gateway socket into spores you baked yourself or otherwise
trust. Operator grants live in `~/.config/cleanroom/gateway.yaml`.

## Composable Plumbing

`compile` and `stamp` are the pieces behind `bake`; use them to drive spore
directly or in CI policy checks:

```bash
eval "spore create name $(cleanroom compile .) $(cleanroom stamp .)"
```

## Policy Quick Reference

```yaml
version: 1
sandbox:
  image:
    ref: ghcr.io/org/image@sha256:...   # digest-pinned, required
  resources:
    memory: 1gb
  network:
    default: deny                        # required
    allow:
      - host: github.com
        ports: [443]
  warmup:
    - "npm ci"
  mediation:
    services: [github-token]
```

Compile fails closed on anything SporeVM cannot enforce (stage-scoped
network, docker, dependency/service blocks, `run.before`, IPv6 literal
hosts). See `docs/policy.md` for the full reference.