generated from coulomb/repo-seed
Update SCOPE, gap analysis, and propose SAND-WP-0004
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.
This commit is contained in:
268
SCOPE.md
268
SCOPE.md
@@ -1,68 +1,63 @@
|
||||
---
|
||||
domain: infotech
|
||||
repo: sand-boxer
|
||||
updated: "2026-06-22"
|
||||
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.
|
||||
> It is intentionally lightweight and may be incomplete until implementation lands.
|
||||
|
||||
---
|
||||
|
||||
## One-liner
|
||||
|
||||
Sandbox provisioning and profile catalog for Custodian — isolated execution
|
||||
environments where agents and automations can develop, build, and test without
|
||||
depending on the workstation filesystem or blast radius.
|
||||
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 **execution isolation and provisioning service** for agentic
|
||||
development and related workloads in the Custodian ecosystem. It answers where
|
||||
work can run safely, how isolation is enforced, how sandboxes phone home, and
|
||||
what happened during their lifecycle.
|
||||
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 **sandbox profile** is a named, versioned recipe (compose stack, VM image,
|
||||
future cluster worker) with documented inputs, outputs, host placement, TTL,
|
||||
and teardown guarantees. Operators and agents request a profile; sand-boxer
|
||||
provisions an isolated environment on a registered host, exposes reachability
|
||||
through ops-bridge (without owning tunnels), registers lifecycle state with
|
||||
State Hub, and tears down on expiry or explicit release.
|
||||
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.
|
||||
|
||||
The repo consolidates patterns today split across `the-custodian`:
|
||||
`e2e-framework/` (SSH + compose sandboxes for cross-repo e2e) and
|
||||
`infra/build-machines/` (Packer VMs with build-agent self-registration).
|
||||
**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
|
||||
|
||||
- **Sandbox profile catalog** — versioned definitions for compose-based e2e
|
||||
stacks, VM images, and future worker patterns; inputs, outputs, and teardown
|
||||
contracts documented per profile
|
||||
- **Provision / wait / teardown lifecycle** — TTL, idempotent cleanup, port and
|
||||
network conventions, observable states (create → ready → active → expired →
|
||||
destroyed)
|
||||
- **Host placement policy** — which profiles run on sandboxer01, CoulombCore
|
||||
interim, or other registered hosts; blast-radius isolation from Railiance01
|
||||
production
|
||||
- **CLI and/or API** — request, inspect, and release sandboxes for operators
|
||||
(`adm`), agents (`agt`), and automations (`atm`)
|
||||
- **State Hub registration contract** — extend the `build-agent` self-register
|
||||
pattern to generic sandbox identities and lifecycle events
|
||||
- **Capability registry entries** in `registry/` for federation via
|
||||
reuse-surface (e.g. `capability.execution.sandbox-provision`)
|
||||
- **Runbooks, templates, and tests** — Packer/compose bundles, operator
|
||||
runbooks, and automated tests for profile lifecycle
|
||||
- **Migration path** — documented cutover from `the-custodian/e2e-framework`
|
||||
and `infra/build-machines` callers to sand-boxer profiles
|
||||
- **Agent and workplan metadata** — `INTENT.md`, `AGENTS.md`, `workplans/`,
|
||||
and State Hub progress/decision logging per ADR-001
|
||||
- **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`
|
||||
|
||||
---
|
||||
|
||||
@@ -70,92 +65,90 @@ The repo consolidates patterns today split across `the-custodian`:
|
||||
|
||||
| Concern | Owner |
|
||||
|---------|--------|
|
||||
| Workstream, task, and progress state | `state-hub` |
|
||||
| Cron and event-triggered orchestration | `activity-core` |
|
||||
| SSH reverse tunnels and tunnel health | `ops-bridge` |
|
||||
| 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, charters, agent instruction canon | `the-custodian` |
|
||||
| Capability index federation hub | `reuse-surface` |
|
||||
| Production service deployment on Railiance01 | `railiance-apps` / domain repos |
|
||||
| Railiance01 cluster operations | `railiance-cluster` / `railiance-infra` |
|
||||
| ADR-001 workplan ↔ DB reconciliation | `state-hub` (`consistency_check.py`) |
|
||||
| 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 may **consume** connectivity (ops-bridge) and certificates
|
||||
(ops-warden); it must not duplicate or subsume those authorities.
|
||||
|
||||
Additional boundaries:
|
||||
|
||||
- **Scheduling** — activity-core decides *when* work runs; sand-boxer decides
|
||||
*where* isolated execution happens
|
||||
- **Workstation as runtime** — the laptop/WSL anchor is interim control plane,
|
||||
not the target execution surface
|
||||
- **Irreversible operational decisions** — host provisioning, production
|
||||
cutovers, and CA policy changes require human approval
|
||||
sand-boxer **consumes** ops-bridge and ops-warden for reachability; it does not
|
||||
own tunnels or CAs.
|
||||
|
||||
---
|
||||
|
||||
## Relevant When
|
||||
|
||||
- An agent or automation needs an isolated environment for coding, building, or
|
||||
testing without laptop filesystem dependence
|
||||
- Cross-repo e2e tests need a remote compose sandbox with guaranteed teardown
|
||||
- A build or verification workload should run on dedicated hardware
|
||||
(sandboxer01) rather than Railiance01 production or the workstation
|
||||
- activity-core or CI needs a bounded execution venue with State Hub visibility
|
||||
- Planning reuse of sandbox provisioning across repos (registry-first discovery)
|
||||
- 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
|
||||
|
||||
- All work runs locally with acceptable blast radius
|
||||
- Only tunnel connectivity is needed (use `ops-bridge` directly)
|
||||
- Only task/workstream state is needed (use `state-hub`)
|
||||
- Only scheduling or rule evaluation is needed (use `activity-core`)
|
||||
- Deploying or operating production services on Railiance01
|
||||
- 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:** bootstrap — repo registered with State Hub; charter written;
|
||||
implementation not started
|
||||
- **Implementation:** v0 — CLI, profiles, `ext.compose-ssh`, State Hub events, HTTP stub
|
||||
- **Docs:** `INTENT.md` (charter, 2026-06-21); `README.md` (one-liner);
|
||||
`AGENTS.md` and `.custodian-brief.md` (State Hub integration, generated)
|
||||
- **Registry:** scaffold present (`registry/indexes/capabilities.yaml` empty;
|
||||
`registry/capabilities/` placeholder); domain in index still `helix_forge`
|
||||
from scaffold — needs alignment to `infotech`
|
||||
- **Workplans:** `SAND-WP-0001`–`0002` finished; `SAND-WP-0008` finished
|
||||
(host telemetry / self-canary)
|
||||
- **Lineage (external, not yet migrated):** `the-custodian/e2e-framework/`
|
||||
(CUST-WP-0028, completed) and `infra/build-machines/` (CUST-WP-0032)
|
||||
- **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
|
||||
|
||||
- Read the charter (`INTENT.md`) and integration instructions (`AGENTS.md`)
|
||||
- Track bootstrap tasks via `workplans/SAND-WP-0001-statehub-bootstrap.md`
|
||||
- Log progress and decisions to State Hub when the hub is reachable
|
||||
- Use **interim** sandbox execution via `the-custodian` directly:
|
||||
- `make e2e REPO=<repo>` (e2e-framework on railiance01/CoulombCore)
|
||||
- `infra/build-machines/` Packer VMs with build-agent registration
|
||||
```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)
|
||||
|
||||
Nothing in **this repo** provisions or manages sandboxes yet.
|
||||
# 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
|
||||
|
||||
- Request a sandbox through sand-boxer CLI or API
|
||||
- Select a named, versioned profile from this repo's catalog
|
||||
- Register `capability.execution.sandbox-provision` (index entry absent)
|
||||
- Automatic lifecycle registration of generic sandbox identities in State Hub
|
||||
- Host placement on sandboxer01 via sand-boxer policy (host may not exist yet)
|
||||
- activity-core or agents invoking sand-boxer without workstation repo paths
|
||||
- Local install/test/lint/build commands documented for this repo (no package
|
||||
layout 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)
|
||||
|
||||
---
|
||||
|
||||
@@ -163,74 +156,55 @@ Nothing in **this repo** provisions or manages sandboxes yet.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
AC[activity-core] -->|when| SB[sand-boxer]
|
||||
AGT[agents / atm] -->|request sandbox| SB
|
||||
SB -->|provision / teardown| HOST[sandboxer01 / interim host]
|
||||
SB -->|lifecycle events| SH[state-hub]
|
||||
SB -->|reachability| OB[ops-bridge]
|
||||
SB -->|SSH identity| OW[ops-warden]
|
||||
RS[reuse-surface] -->|federate| REG[registry/]
|
||||
TC[the-custodian e2e + build-machines] -.->|migrate from| SB
|
||||
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
|
||||
```
|
||||
|
||||
- **Upstream dependencies:** ops-bridge (tunnels), ops-warden (certs, optional),
|
||||
State Hub (registration API), registered sandbox hosts (SSH + Docker/Packer)
|
||||
- **Downstream consumers:** LLM agents, activity-core instructions, CI hooks,
|
||||
cross-repo e2e callers migrating off `the-custodian`
|
||||
- **Often used with:** `activity-core` (orchestration), `state-hub` (visibility),
|
||||
`reuse-surface` (capability discovery)
|
||||
|
||||
---
|
||||
|
||||
## Terminology
|
||||
|
||||
- **Profile** — named, versioned sandbox type with provision/teardown contract
|
||||
- **Sandbox** — a running isolated environment instance of a profile
|
||||
- **Host placement** — policy mapping profiles to sandboxer01, CoulombCore, etc.
|
||||
- **TTL** — time-to-live; sandboxes are disposable by default
|
||||
- **Phone home** — reachability and registration via ops-bridge + State Hub
|
||||
- Actor types (consumers): `adm` (operator), `agt` (LLM agent), `atm` (automation)
|
||||
- **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
|
||||
|
||||
- `the-custodian` — current home of e2e-framework and build-machines; governance
|
||||
canon; sand-boxer extracts reusable execution platform from here
|
||||
- `ops-bridge` — SSH reverse tunnels; sand-boxer orchestrates reachability, does
|
||||
not run tunnel daemons
|
||||
- `ops-warden` — SSH CA and certificate issuance
|
||||
- `state-hub` — workstream/task state and sandbox lifecycle visibility
|
||||
- `activity-core` — schedules work; may request sandboxes as execution venue
|
||||
- `reuse-surface` — federates `registry/` capability entries
|
||||
- `railiance-cluster` / `railiance-apps` — production layer; explicitly not
|
||||
sandbox execution surface
|
||||
- **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
|
||||
|
||||
*Planned — not yet registered in `registry/indexes/capabilities.yaml`.*
|
||||
|
||||
```capability
|
||||
type: execution
|
||||
title: Sandbox provisioning
|
||||
description: Isolated execution environments for agentic development, e2e testing, and bounded automations — profile-based provision, TTL teardown, and State Hub lifecycle registration.
|
||||
keywords: [sandbox, isolation, provision, e2e, agentic, execution, profile]
|
||||
```
|
||||
|
||||
Target registry id: `capability.execution.sandbox-provision` (or equivalent per
|
||||
reuse-surface naming).
|
||||
Registered (draft): `capability.execution.sandbox-provision` —
|
||||
see `registry/capabilities/execution.sandbox-provision.md`.
|
||||
|
||||
---
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
- Start with: `INTENT.md` (meta-framework charter)
|
||||
- Research: `research/` (landscape, reference systems, design synthesis)
|
||||
- Agent instructions: `AGENTS.md` (State Hub session protocol)
|
||||
- Offline brief: `.custodian-brief.md`
|
||||
- Workplans: `workplans/` (bootstrap: `SAND-WP-0001`)
|
||||
- Registry authoring: `registry/README.md`
|
||||
- Lineage reference (external): `the-custodian/e2e-framework/RUNBOOK.md`,
|
||||
`the-custodian/infra/build-machines/README.md`
|
||||
| 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
Block a user