coulomb/sand-boxer
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7cabf77fb66bbfde6d12757b510e0d713457a0fa
sand-boxer/SCOPE.md
tegwick 15f031fd65 feat: cloud adapters E2B/Modal and billing export (SAND-WP-0010) 
Add credentialed E2B and Modal extensions, burst routing fallback,
fin-hub meter export hook, BYOK docs, and 77 tests.
2026-06-24 12:50:19 +02:00

9.7 KiB
Raw Blame History

domain, repo, updated
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
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–0010 (0003/0004 in sibling repos)
  • Workplans ready: SAND-WP-0011–0012 (consumers, Packer)
  • 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
  • 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: 77 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: SAND-WP-0011 (consumer profiles), 0012 (Packer orchestration).

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]
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 — SAND-WP-0012
  • Real E2B / Modal adapters — done (SAND-WP-0010)
  • Consumer profiles (agent-dev, build) — SAND-WP-0011
  • Cross-host snapshot transfer
  • Formal ops-bridge tunnel attachment — SAND-WP-0011
  • 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
Reference in New Issue View Git Blame Copy Permalink