coulomb/sand-boxer
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1415e17230485a2bef9c0ce9fe71a45a3f0ac1ca
sand-boxer/SCOPE.md
tegwick 1415e17230 Implement SAND-WP-0006: SaaS payments, routing, and ext.saas-stub 
Add credits store, metering on create/destroy, extension routing resolver,
metered SaaS stub extension, burst/saas profiles, credits CLI, docs, and tests.
2026-06-24 07:52:20 +02:00

7.4 KiB
Raw Blame History

domain, repo, updated
domain repo updated
infotech sand-boxer 2026-06-23

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, 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/; infra/build-machines/ remains future ext.vm-packer work.

In Scope

  • Unified establishment API — CLI v0 + HTTP stub (create, get, list, destroy, recreate); fuller surface (extend_ttl, snapshot) planned
  • Profile catalog — profile.compose-e2e, profile.sandbox-canary; more profiles and extensions over time
  • Extension platform — ext.compose-ssh (SSH + compose); plugin contract in docs/meta-framework.md
  • Host placement — profile placement + SANDBOXER_HOST overrides; sandboxer01 preferred, CoulombCore interim
  • Lifecycle + State Hub — transitions emit progress events; JSON store at ~/.local/share/sandboxer/sandboxes.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
SaaS sandbox metering / payments Future SAND-WP-0006

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
  • 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
  • Workplans finished: SAND-WP-0001–0005, 0008 (see workplans/)
  • Package: src/sandboxer/ — CLI, manager, extensions, telemetry, HTTP API
  • Profiles: profile.compose-e2e, profile.sandbox-canary, profile.vm-haskell-build
  • Extensions: ext.compose-ssh, ext.vm-packer, ext.saas-stub (metered)
  • Routing + payments: docs/routing.md, docs/payments.md, sandboxer credits
  • Registry: capability.execution.sandbox-provision indexed (draft)
  • Tests: 26 pytest cases; make check green
  • Sibling: wise-validator ships validate run (SAND-WP-0003)

Latest gap analysis: history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md

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 destroy <id>
sandboxer inspect host / inspect stale / reap-stale
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 (when hub reachable)
  • HTTP API via uvicorn sandboxer.api.app:app
  • Operator runbooks under docs/runbooks/

What Is Not Possible Yet

  • make e2e REPO= shim — done (SAND-WP-0004; delegates to validate run)
  • TTL auto-expiry / extend_ttl enforcement
  • ext.vm-packer attach mode — done (SAND-WP-0005); Packer build orchestration deferred
  • Real E2B / Modal adapters (stub + payments v0 done in SAND-WP-0006)
  • Snapshot / restore / checkpoint profiles (SAND-WP-0007)
  • Formal ops-bridge tunnel attachment in reachability descriptor
  • Dedicated sandboxer01 host (CoulombCore interim only today)
  • reuse-surface validate / federation publish workflow
  • .repo-classification.yaml (State Hub C-24 hygiene)

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 e2e-framework] -.->|migrate| WV
  TC -.->|provision migrate| SB

Terminology

  • Profile — named sandbox recipe (extension binding, placement, TTL metadata)
  • Extension — backend adapter (provision, wait_ready, teardown)
  • Establishment — create through ready (distinct from validation pass/fail)
  • 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/; shim migration pending
  • 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/host-telemetry.md Canary and inventory
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