---
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 |