sand-boxer/SCOPE.md

---
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–0008 (all workplans in `workplans/`;
  0003/0004 delivered in sibling repos wise-validator / the-custodian)
- **Package:** `src/sandboxer/` — CLI, manager, extensions, routing, payments,
  snapshots, telemetry, HTTP API
- **Profiles:** `profile.compose-e2e`, `profile.compose-checkpoint`,
  `profile.sandbox-canary`, `profile.vm-haskell-build`, `profile.saas-stub`,
  `profile.burst-sandbox`
- **Extensions:** `ext.compose-ssh` (compose + tar snapshots),
  `ext.vm-packer` (attach), `ext.saas-stub` (metered stub + metadata snapshots)
- **Docs:** `meta-framework`, `extension-sdk`, `host-telemetry`, `routing`,
  `payments`, `snapshots`, `migration-gaps`, `migration-build-machines`
- **Registry:** `capability.execution.sandbox-provision` indexed (draft)
- **Tests:** 69 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`  
Latest workplan: **SAND-WP-0009** (TTL enforcement — finished).

---

## 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]
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` (attach-only today)
- Real E2B / Modal / Daytona adapters (in-repo stub only)
- Cross-host snapshot transfer
- Formal ops-bridge tunnel attachment in reachability descriptor
- Dedicated sandboxer01 host (CoulombCore interim only today)
- `reuse-surface validate` / federation publish workflow
- ~~`.repo-classification.yaml`~~ — done (SAND-WP-0009)
- fin-hub billing export for metered usage

---

## 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 |