diff --git a/PLANNING/boris-methodology-upgrade/PHASE-7-AGENT-SANDBOXES.md b/PLANNING/boris-methodology-upgrade/PHASE-7-AGENT-SANDBOXES.md new file mode 100644 index 0000000..992c5a7 --- /dev/null +++ b/PLANNING/boris-methodology-upgrade/PHASE-7-AGENT-SANDBOXES.md @@ -0,0 +1,148 @@ +# Phase 7: Agent Sandboxes (Factory In A Box) + +**Objective:** Give the orchestrator a way to run each subagent/task inside a throwaway, credential-isolated VM instead of the shared local machine — extending Phase 6's parallel-session work with real isolation. + +**Source:** exe.dev / IndyDevDan, ["Engineers... Your Software Factory NEEDS Agent Sandboxes to SCALE"](https://youtu.be/SEI_qIW4o2c). Indexed and queried via TwelveLabs Jockey (`Agentic Engineering Builds` knowledge store). + +--- + +## The Framework, As Described in the Source + +**An agent sandbox is a throwaway VM**, not a git worktree or container — the video explicitly shows a *"throwaway exe.dev VM"* with SSH access and a provisioning-key connection from host into sandbox. + +**Structure — "Factory In A Box":** `host → sandbox → factory → app`. The host connects into a disposable sandbox; the sandbox contains a factory (deterministic Python + bounded agents); the factory builds the app ("inkwell"). Inside each sandbox sits its own orchestrator plus a full agent pipeline — request → plan → build → test → review → document — so each agent effectively "owns its own computer" instead of sharing the local machine. + +**Security contract — explicit and load-bearing:** *"keys never enter"* the sandbox. The host retains all sensitive credentials; the sandbox is disposable by design, so nothing valuable is lost if it's compromised or simply torn down. + +**Lifecycle:** +1. Outer orchestrator provisions a VM sandbox +2. Mount/create the sandbox environment +3. Host connects in via SSH / provisioning key (no credentials cross the boundary) +4. In-sandbox orchestrator runs +5. Worker agents carry out the SDLC chain (request → plan → build → test → review → document) +6. Sandbox is torn down — throwaway by design + +--- + +## Fit Against This Repo + +| Location | What's there now | Gap | +|---|---|---| +| `SUBAGENT-FRAMEWORK/` | Orchestrator-centered architecture, file-based memory, parallel/sequential subagent execution | No VM isolation layer, no "keys never enter" credential boundary — subagents share one filesystem and inherit host credentials | +| `PLANNING/boris-methodology-upgrade/PHASE-6-PARALLEL-CLOUD-SESSIONS.md` | "Parallel sessions" via numbered terminal tabs, using git as the sync point | Coordination-by-convention on a shared machine — the opposite of "each agent owns its own computer" | +| `openclaw-agents:clawbox-deploy` skill | Already VM-based: deploys OpenClaw instances inside Clawbox macOS VMs on headless Mac Minis, with Tailscale mesh and SSH-style remote management (`clawbox-manage`) | Currently scoped to long-lived per-client agents, not throwaway per-task software-factory sandboxes. No "keys never enter" contract documented, no teardown-by-design lifecycle. | +| `.claude/hooks/` | `session-start-ablation-check.md`, `stop-verification-evidence.md` | No sandbox-lifecycle hook (provision on start, teardown on stop) | + +**Verdict:** the closest infrastructure precedent already exists in-house — **Clawbox** (VM-based, SSH-managed, Tailscale-meshed agent deployment). This framework isn't a net-new primitive; it's Clawbox's philosophy retargeted from "one persistent VM per client" to "one throwaway VM per task," plus the explicit "keys never enter" credential boundary Clawbox doesn't currently formalize. + +Git worktrees stay useful as a lighter-weight tier for same-machine parallel sessions (what Phase 6 already covers), but they are **not** what this framework uses for isolation — VM sandboxes are the isolated/untrusted-work tier, worktrees are the lightweight tier. + +--- + +## Proposed Structure + +``` +organized-codebase/ +├── SUBAGENT-FRAMEWORK/ +│ └── sandboxes/ # NEW +│ ├── README.md # host→sandbox→factory→app contract, "keys never enter" rule +│ ├── provision-sandbox.sh # spins up a throwaway VM (Clawbox-style) +│ ├── connect-sandbox.sh # SSH/provisioning-key connection, no credentials copied in +│ └── teardown-sandbox.sh # tears the VM down when the SDLC chain completes +├── .claude/ +│ ├── hooks/ +│ │ ├── sandbox-session-start.md # NEW: provision + connect before work begins +│ │ └── sandbox-session-stop.md # NEW: teardown, confirm no keys were copied in +│ └── skills/ +│ └── agent-sandbox-provisioner/ # NEW skill, distributable like organized-codebase-applicator +└── PLANNING/boris-methodology-upgrade/ + └── PHASE-7-AGENT-SANDBOXES.md # this file +``` + +### Why lean on Clawbox instead of building fresh VM tooling + +- Clawbox VMs already run on headless Mac Minis with Tailscale + SSH — the exact primitives the source video shows (throwaway VM, provisioning-key connection) +- `clawbox-manage` already covers lifecycle operations (status, restart, logs, recreate) — teardown-by-design is a config change, not new tooling +- The one real gap to close: formalizing "keys never enter" as an explicit, enforced rule (host holds credentials, sandbox never receives them) — Clawbox doesn't document this boundary today + +--- + +## Tasks + +### Task 1: Define the Sandbox Contract +Write `SUBAGENT-FRAMEWORK/sandboxes/README.md` documenting: +- The `host → sandbox → factory → app` structure +- The "keys never enter" rule — explicit and enforced, not just documented +- What state a sandbox owns vs. what stays on the host + +### Task 2: Retarget Clawbox Provisioning +Reuse `clawbox-deploy`'s VM/Tailscale/SSH pattern, retargeted for throwaway, per-task sandboxes instead of persistent per-client agents. Teardown-by-design instead of persistent-by-default. + +### Task 3: Build Provision/Connect/Teardown Scripts +``` +SUBAGENT-FRAMEWORK/sandboxes/provision-sandbox.sh +SUBAGENT-FRAMEWORK/sandboxes/connect-sandbox.sh +SUBAGENT-FRAMEWORK/sandboxes/teardown-sandbox.sh +``` + +### Task 4: Wire In Session-Lifecycle Hooks +``` +.claude/hooks/sandbox-session-start.md # provision + connect before work begins +.claude/hooks/sandbox-session-stop.md # teardown + verify no credentials were copied in +``` + +### Task 5: Package as a Distributable Skill +`.claude/skills/agent-sandbox-provisioner/` — same shape as `organized-codebase-applicator`. + +### Task 6: Update the SUBAGENT-FRAMEWORK Orchestrator +Outer orchestrator provisions one sandbox per subagent/task. In-sandbox orchestrator runs the request → plan → build → test → review → document chain, matching the source framework's pipeline. + +--- + +## Verification Checklist + +- [ ] Sandbox contract documented and the "keys never enter" rule is enforced (not just written down) +- [ ] Clawbox provisioning retargeted for throwaway per-task use +- [ ] Provision/connect/teardown scripts tested on a throwaway task +- [ ] Confirmed no host credentials are ever present inside a sandbox +- [ ] Session-lifecycle hooks fire correctly on start/stop +- [ ] Skill installs cleanly via the existing skill-creator-enhanced pattern +- [ ] Orchestrator provisions one sandbox per subagent/task + +--- + +## Prompt Template + +``` +claude --dangerously-skip-permissions + +Read PLANNING/boris-methodology-upgrade/PHASE-6-PARALLEL-CLOUD-SESSIONS.md, +SUBAGENT-FRAMEWORK/README.md, and the openclaw-agents:clawbox-deploy and +clawbox-manage skill docs for existing conventions this must build on. + +Build the agent-sandboxes capability described in +PLANNING/boris-methodology-upgrade/PHASE-7-AGENT-SANDBOXES.md. +Use the Organized Codebase agent templates in .claude/{skills,commands,agents} +as a first step. + +Core contract (from the exe.dev "Factory In A Box" framework): +- Structure: host → sandbox → factory → app +- Sandbox = a throwaway VM (reuse the Clawbox provisioning pattern, retargeted + from persistent-per-client to disposable-per-task) +- Security rule, non-negotiable: "keys never enter" — the host retains all + credentials; the sandbox never receives them +- Inside each sandbox: its own orchestrator running the SDLC chain + (request → plan → build → test → review → document) + +Work through Tasks 1-6 in order. Verify each against the checklist before +moving to the next. +``` + +--- + +## Completion + +When complete: +1. Test sandbox provision → connect → run → teardown on a throwaway task +2. Confirm no host credentials are ever present inside a sandbox +3. Git commit: "Phase 7: Agent sandboxes (Factory In A Box)"