generated from coulomb/repo-seed
tegwick
774bc5ae0a
Add vm-packer build mode, profile.vm-packer-build, State Hub progress notes during long provision, docs/runbook, and build mode tests.
256 lines
10 KiB
Markdown
256 lines
10 KiB
Markdown
---
|
||
domain: infotech
|
||
repo: sand-boxer
|
||
updated: "2026-06-24"
|
||
---
|
||
|
||
# SCOPE
|
||
|
||
> This file helps you quickly understand what this repository is about,
|
||
> when it is relevant, and when it is not.
|
||
|
||
---
|
||
|
||
## One-liner
|
||
|
||
Coulomb meta-framework for **establishing sandboxes** — profile-based provision,
|
||
extension routing, workspace checkpoints, lifecycle registration, and host
|
||
telemetry — so agents and automations run in isolated venues without workstation
|
||
blast radius.
|
||
|
||
---
|
||
|
||
## Core Idea
|
||
|
||
sand-boxer is the **sandbox establishment service** (OpenRouter for sandboxes).
|
||
It answers which recipe applies, which backend fulfills it, where it runs, and
|
||
what happened during lifecycle. It is **self-sustained** — it does not depend on
|
||
wise-validator or other sibling projects.
|
||
|
||
A **profile** is a named, versioned recipe bound to an **extension** (backend
|
||
adapter). Consumers request `create`; sand-boxer provisions on a placement host,
|
||
confirms reachability (`ready`), emits State Hub lifecycle events, and tears down
|
||
on destroy or operator reap.
|
||
|
||
**wise-validator** (separate repo) consumes sand-boxer for cross-repo e2e
|
||
validation; sand-boxer does not run health checks or test commands.
|
||
|
||
Lineage: provision/teardown extracted from `the-custodian/e2e-framework/`;
|
||
`ext.vm-packer` attach mode covers build-machine workspaces; full Packer build
|
||
orchestration from `create` remains deferred.
|
||
|
||
---
|
||
|
||
## In Scope
|
||
|
||
- **Unified establishment API** — CLI v0 + HTTP stub (`create`, `get`, `list`,
|
||
`destroy`, `recreate`, `snapshot`, `restore`, `extend-ttl`, `expire`)
|
||
- **Profile catalog** — six profiles: compose e2e/checkpoint, sandbox canary,
|
||
vm-haskell-build, saas-stub, burst-sandbox
|
||
- **Extension platform** — `ext.compose-ssh`, `ext.vm-packer`, `ext.saas-stub`;
|
||
plugin contract in `docs/meta-framework.md` and `docs/extension-sdk.md`
|
||
- **Routing engine** — `RouteSpec` strategies (`prefer-self-hosted`, `lowest-cost`,
|
||
`lowest-latency`, `explicit`); see `docs/routing.md`
|
||
- **Payments v0** — credits store, pre-create balance check, post-destroy debit
|
||
for metered extensions; see `docs/payments.md`
|
||
- **Workspace checkpoints** — snapshot index + extension hooks; see `docs/snapshots.md`
|
||
- **Host placement** — profile `placement` + `SANDBOXER_HOST` overrides;
|
||
sandboxer01 preferred, CoulombCore interim
|
||
- **Lifecycle + State Hub** — transitions emit progress events; JSON stores at
|
||
`~/.local/share/sandboxer/sandboxes.json` and `snapshots.json`
|
||
- **Host telemetry** — canary self-deploy, `inspect host` / `inspect stale`,
|
||
`reap-stale` (SAND-WP-0008)
|
||
- **Capability registry** — `capability.execution.sandbox-provision` (draft)
|
||
- **Sibling integration contracts** — `docs/integrations/` (glas-harness,
|
||
wise-validator, snuggle-inventor)
|
||
- **Runbooks and smoke** — compose-e2e, sandbox-canary; remote smoke scripts
|
||
- **Workplans and charter** — ADR-001 files in `workplans/`, `INTENT.md`
|
||
|
||
---
|
||
|
||
## Out of Scope
|
||
|
||
| Concern | Owner |
|
||
|---------|--------|
|
||
| E2e health checks, test execution, validation results | **wise-validator** |
|
||
| Agent gateway, tools, memory | **glas-harness** |
|
||
| Code generation, tech specs | **snuggle-inventor** |
|
||
| Workstream / task state | `state-hub` |
|
||
| Scheduling | `activity-core` |
|
||
| SSH tunnels | `ops-bridge` |
|
||
| SSH certificate issuance | `ops-warden` |
|
||
| Canon and agent instruction canon | `the-custodian` |
|
||
| Capability federation hub | `reuse-surface` |
|
||
| Production on Railiance01 | `railiance-apps` / domain repos |
|
||
| Real E2B / Modal / Daytona cloud APIs | Future adapters (stub in-repo) |
|
||
| fin-hub billing export | Future |
|
||
|
||
sand-boxer **consumes** ops-bridge and ops-warden for reachability; it does not
|
||
own tunnels or CAs.
|
||
|
||
---
|
||
|
||
## Relevant When
|
||
|
||
- Provisioning an isolated compose stack on CoulombCore / sandboxer01
|
||
- Attaching a workspace on a pre-built VM (`profile.vm-haskell-build`)
|
||
- Saving or restoring a workspace checkpoint (`profile.compose-checkpoint`)
|
||
- Choosing self-hosted vs metered SaaS backend (`profile.burst-sandbox`)
|
||
- Canary self-deploy or host inventory before placing workloads
|
||
- activity-core, CI, glas-harness, or wise-validator need a sandbox handle
|
||
- Discovering sandbox capability via `registry/`
|
||
- Migrating off `the-custodian/e2e-framework` provision path
|
||
|
||
---
|
||
|
||
## Not Relevant When
|
||
|
||
- Running repo e2e tests end-to-end (use **wise-validator** `validate run`)
|
||
- Local-only work with acceptable blast radius
|
||
- Tunnel or cert operations alone (ops-bridge / ops-warden)
|
||
- Task/workstream tracking alone (state-hub)
|
||
|
||
---
|
||
|
||
## Current State
|
||
|
||
- **Status:** v0 operational — self-hosted compose path proven on CoulombCore;
|
||
routing, payments stub, and snapshots shipped
|
||
- **Workplans finished:** SAND-WP-0001–0012 (0003/0004 in sibling repos)
|
||
- **Workplans ready:** none (reuse-surface publish / sandboxer01 operator track)
|
||
- **Package:** `src/sandboxer/` — CLI, manager, extensions, routing, payments,
|
||
snapshots, telemetry, HTTP API
|
||
- **Profiles:** compose e2e/checkpoint, canary, vm-haskell-build, saas-stub,
|
||
burst-sandbox, e2b-burst, modal-gpu, agent-dev, build, vm-packer-build
|
||
- **Extensions:** `ext.compose-ssh`, `ext.vm-packer`, `ext.saas-stub`,
|
||
`ext.e2b`, `ext.modal`
|
||
- **Docs:** `meta-framework`, `extension-sdk`, `host-telemetry`, `routing`,
|
||
`payments`, `snapshots`, `migration-gaps`, `migration-build-machines`
|
||
- **Registry:** `capability.execution.sandbox-provision` indexed (draft)
|
||
- **Tests:** 90 pytest cases; `make check` green
|
||
- **Siblings:** wise-validator `validate run` (SAND-WP-0003); the-custodian
|
||
`make e2e REPO=` shim (SAND-WP-0004)
|
||
|
||
Latest gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
|
||
Gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
|
||
**Ready workplans:** none — gap analysis items complete; operator tracks remain.
|
||
|
||
---
|
||
|
||
## What Is Possible Now
|
||
|
||
```bash
|
||
make setup && make install # sandboxer CLI
|
||
sandboxer create # canary self-deploy (no args)
|
||
sandboxer create --profile profile.compose-e2e --input repo=/path/to/repo
|
||
sandboxer create --profile profile.vm-haskell-build --input vm=haskell-build --input repo=/path
|
||
sandboxer create --profile profile.burst-sandbox # routes to saas-stub when needed
|
||
sandboxer get <id> / list / destroy / recreate
|
||
sandboxer snapshot <id> [--name LABEL]
|
||
sandboxer restore <snapshot_id>
|
||
sandboxer snapshots list / snapshots get <id>
|
||
sandboxer extend-ttl <id> --duration 2h
|
||
sandboxer expire [--apply]
|
||
sandboxer create --ttl 2h ...
|
||
sandboxer credits show / credits add <amount>
|
||
sandboxer inspect host / inspect stale / reap-stale [--apply]
|
||
sandboxer reachability show <id>
|
||
sandboxer create --profile profile.agent-dev --input repo=/path --actor agt --project glas-harness
|
||
sandboxer create --profile profile.build --input vm=haskell-build --actor agt --project snuggle-inventor
|
||
sandboxer create --profile profile.vm-packer-build --input packer_template=... --input vm_name=haskell-build
|
||
make smoke-remote # CoulombCore compose smoke (SANDBOXER_HOST)
|
||
|
||
# Full e2e validation (wise-validator, separate install):
|
||
validate run ~/activity-core
|
||
|
||
# Legacy operator entry (the-custodian):
|
||
cd ~/the-custodian && make e2e REPO=activity-core
|
||
```
|
||
|
||
- State Hub lifecycle events on create/destroy/snapshot (when hub reachable)
|
||
- HTTP API via `uvicorn sandboxer.api.app:app` (sandboxes + snapshots)
|
||
- Operator runbooks under `docs/runbooks/`
|
||
|
||
---
|
||
|
||
## What Is Not Possible Yet
|
||
|
||
- ~~TTL auto-expiry / `extend_ttl` enforcement~~ — done (SAND-WP-0009)
|
||
- ~~Packer build orchestration from `create`~~ — done (SAND-WP-0012)
|
||
- ~~Real E2B / Modal adapters~~ — done (SAND-WP-0010)
|
||
- ~~Consumer profiles (agent-dev, build)~~ — done (SAND-WP-0011)
|
||
- Cross-host snapshot transfer
|
||
- ~~Formal ops-bridge tunnel attachment~~ — done (SAND-WP-0011; descriptor only)
|
||
- Dedicated sandboxer01 host (CoulombCore interim only today)
|
||
- `reuse-surface validate` / federation publish workflow
|
||
- ~~`.repo-classification.yaml`~~ — done (SAND-WP-0009)
|
||
- ~~fin-hub billing export~~ — hook done (SAND-WP-0010); railiance-platform wiring operator
|
||
|
||
---
|
||
|
||
## How It Fits
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
WV[wise-validator] -->|create/destroy| SB[sand-boxer]
|
||
GH[glas-harness] -->|create| SB
|
||
AC[activity-core] -->|when| WV
|
||
AC -->|venue request| SB
|
||
SB -->|provision| HOST[CoulombCore / sandboxer01]
|
||
SB -->|lifecycle| SH[state-hub]
|
||
SB -->|SSH reachability| OB[ops-bridge]
|
||
TC[the-custodian] -.->|make e2e shim| WV
|
||
TC -.->|provision| SB
|
||
```
|
||
|
||
---
|
||
|
||
## Terminology
|
||
|
||
- **Profile** — named sandbox recipe (extension binding, placement, TTL metadata)
|
||
- **Extension** — backend adapter (`provision`, `wait_ready`, `teardown`; optional
|
||
`snapshot` / `restore_from_snapshot`)
|
||
- **Establishment** — create through `ready` (distinct from validation pass/fail)
|
||
- **Snapshot** — point-in-time workspace checkpoint; restore creates a new sandbox
|
||
- **Route** — extension selection policy when multiple backends qualify
|
||
- **Canary** — `profile.sandbox-canary` self-deploy with host telemetry
|
||
- Actor types: `adm`, `agt`, `atm`
|
||
|
||
---
|
||
|
||
## Related / Overlapping
|
||
|
||
- **wise-validator** — validation orchestration; one-way consumer of sand-boxer
|
||
- **the-custodian** — legacy `e2e-framework/`; `make e2e` shim delegates to
|
||
wise-validator (SAND-WP-0004)
|
||
- **ops-bridge** / **ops-warden** — connectivity and identity consumers
|
||
- **state-hub** — lifecycle visibility
|
||
- **reuse-surface** — capability federation target
|
||
|
||
---
|
||
|
||
## Provided Capabilities
|
||
|
||
Registered (draft): `capability.execution.sandbox-provision` —
|
||
see `registry/capabilities/execution.sandbox-provision.md`.
|
||
|
||
---
|
||
|
||
## Getting Oriented
|
||
|
||
| Path | Purpose |
|
||
|------|---------|
|
||
| `INTENT.md` | Charter and sibling boundaries |
|
||
| `docs/meta-framework.md` | API, lifecycle, extension contract |
|
||
| `docs/extension-sdk.md` | Extension author guide |
|
||
| `docs/host-telemetry.md` | Canary and inventory |
|
||
| `docs/routing.md` | Backend selection strategies |
|
||
| `docs/payments.md` | Credits and metering |
|
||
| `docs/snapshots.md` | Checkpoint snapshot/restore |
|
||
| `docs/ttl.md` | TTL extend and expire/reap |
|
||
| `docs/security.md` | Blast-radius vs intent enforcement |
|
||
| `docs/migration-gaps.md` | Legacy cutover status |
|
||
| `docs/integrations/` | Consumer contracts |
|
||
| `workplans/` | ADR-001 work structure |
|
||
| `history/` | INTENT ↔ SCOPE assessments |
|
||
| `AGENTS.md` | Session protocol | |