sand-boxer/SCOPE.md

domain	repo	updated
infotech	sand-boxer	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
Workplan / 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/workplan 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, bwrap-local, claude-agent-dev-proof (candidate, not production)
• 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: 172 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

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

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