Sssf Sandbox Orchestrator

SSSF Sandbox Orchestrator

Drives the out-of-sandbox half of this repo: the sbx namespace under just/sandbox/ that take a blank exe.dev VM to a health-checked, running factory in ~10s, run work inside it, expose it to a browser, and — only when a human says so — tear it down.

The one governing principle: THIN SKILL, FAT RECIPES

Every action you take should be a just command a human could type. The recipes hold the knowledge; this skill holds the judgment about which one to run and how to read the result.

• Dropping to ssh <vm>.exe.xyz '...' or curl to inspect is fine and expected — that is what just sbx run cmd <id> '<cmd>' exists for, and reading a log or a table needs no ceremony.
• Re-implementing what a recipe already does is not. Never hand-roll a key mint, a revoke, an ssh exe.dev new, a share port, or a detached nohup launch. Those encode measured facts (mint order, the revocation gate, the proxy retarget, the three detachment pieces) and a hand-rolled version drops one of them silently.
• If a recipe is wrong, fix the recipe and say so. Do not route around it.

Dependencies

This skill references /sssf and /sandbox-exe-dev rather than duplicating them. /sssf owns the ADW roster, the handoff contract and the trace-db schema; /sandbox-exe-dev owns the exe.dev CLI surface. Both move without asking us, and a copy pasted here would be a second source of truth that goes wrong quietly — a stale model id, a renamed flag. Read them; do not quote them.

Preflight is one command. Run it before the first phase; any failure means report and stop, never work around a missing prerequisite by hand.

just sbx manage doctor

It checks all six in one pass: ssh exe.dev reachable, OPENROUTER_PROVISIONING_KEY set (never printed), the run-record helper runs, the provisioner is executable, the models template carries full four-field rate blocks, and the adw layer resolves. Green ends with sbx doctor: OK.

Two things it does not cover, so check them yourself:

Listing a namespace is just --list sbx, not just sbx --list. The latter reads --list as a recipe name and errors with Justfile does not contain recipe `sbx --list` . A bare just sbx also works — it runs the namespace's default, which lists.

Two layers, one credential boundary

The whole repo ships to the sandbox, this skill included. What a sandbox cannot do is USE the out-sandbox half — just sbx mount there fails on a missing exe.dev account, and create fails on a missing OPENROUTER_PROVISIONING_KEY. Neither credential ever leaves the host, and that, not file absence, is what stops a sandbox from mounting sandboxes. Keep the credentials on the host.

The drive surface

Four groups under sbx, plus mount at the top because it is the entry point, not a phase:

just sbx
├── mount              the chain: create → fill → setup → observe
├── lifecycle          the six phases, for when you need one on its own
├── manage             preflight, readback, fleet ops — nothing here is a phase
├── run                put work in / look inside: `run cmd`, `run agent`
└── orch               boot a host-side orchestrator: `orch cc`, `orch pi`

just sbx, just sbx lifecycle, just sbx manage, just sbx run and just sbx orch each list their own contents when run bare.

The run id is the handle for every phase. create appends -<date>-<6 hex> if you did not, and prints what it settled on — use that string, not the one you typed.

The five gate assertions (setup): A git integrity (status --porcelain clean, HEAD matches the recorded sha) · B pi --list-models non-empty — it exits 0 while empty · C every roster model answers a ping · D pi reports non-zero cost, which proves the rate table loaded · E remaining credit. A failure reports, stops, and leaves the VM alive.

Cookbooks (lazy-load the one the request calls for)

References (deep specs, read on demand)

Hard rules

1. Never decide teardown. Report what the run produced, what it cost, and recommend — the human decides. mount stops at observe on purpose and nothing chains into teardown. A VM left running is a bill; a VM destroyed early is the evidence and the artifacts, gone. harvest is the exception you may run freely — it only reads the box and only writes refs/sandbox/, so run it as soon as a run commits rather than letting the commits wait on a teardown decision.
2. Never run ADWs on the host. just adw sdlc "..." here runs the factory on the engineer's laptop — the exact collision this system exists to remove. Work goes in through just sbx lifecycle execute / just sbx run agent, always.
3. A gate failure means STOP and diagnose, never destroy. The VM is left alive deliberately. Read the failing assertion, just sbx run cmd <id> '...' your way to the cause, fix it, re-run just sbx lifecycle setup. Re-running setup is safe.
4. Never touch a key. The runtime key lives at .sandbox/runs/<id>.key (0600) and inside the VM's app/.env. Never print it, never copy it, never pass it over ssh — setup's gate spends it from inside the box for exactly that reason. The provisioning key never leaves the host.
5. Never mint outside create. The sbx- prefix is the entire safety model for reap; the engineer's personal keys carry no prefix and deleting one is unrecoverable.
6. Report the run id every time. It is the only handle the next phase, the next session, and teardown have.