cleanroom

name	cleanroom
description	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.

Cleanroom

Cleanroom is a thin layer over 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:

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:

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:

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

Verify Provenance

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

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:

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:

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

Policy Quick Reference

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.