generated from coulomb/repo-seed
tegwick
1415e17230
Add credits store, metering on create/destroy, extension routing resolver, metered SaaS stub extension, burst/saas profiles, credits CLI, docs, and tests.
212 lines
7.4 KiB
Markdown
212 lines
7.4 KiB
Markdown
---
|
||
domain: infotech
|
||
repo: sand-boxer
|
||
updated: "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
|
||
|
||
```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 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
|
||
|
||
```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 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 | |