generated from coulomb/repo-seed
tegwick
6473fa78d7
Refresh SCOPE.md for v0 operational state after WP-0002/0003/0008. Add history/ INTENT↔SCOPE assessment and ready workplan for the-custodian e2e shim to close the e2e-framework migration arc.
210 lines
7.3 KiB
Markdown
210 lines
7.3 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 (bootstrap), 0002 (meta-framework +
|
|
`ext.compose-ssh`), 0003 (wise-validator extraction, sibling repo), 0008 (host
|
|
telemetry / self-canary)
|
|
- **Package:** `src/sandboxer/` — CLI, manager, extensions, telemetry, HTTP API
|
|
- **Profiles:** `profile.compose-e2e`, `profile.sandbox-canary`
|
|
- **Extensions:** `ext.compose-ssh` only
|
|
- **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
|
|
```
|
|
|
|
- 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=` in the-custodian delegating to sand-boxer (SAND-WP-0004)
|
|
- TTL auto-expiry / `extend_ttl` enforcement
|
|
- `ext.vm-packer` / build-machines migration (SAND-WP-0005)
|
|
- SaaS extensions (E2B, Modal) or payments layer (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 | |