generated from coulomb/repo-seed
docs: charter meta-framework vision, research, and SAND-WP-0002
Rewrite INTENT.md as the sand-boxer meta-framework charter (OpenRouter-style sandbox API, extensions, payments, Coulomb sibling boundaries). Add research under research/, update SCOPE.md, bootstrap workplans SAND-WP-0001/0002, and State Hub integration files from the bootstrap pass.
This commit is contained in:
235
SCOPE.md
Normal file
235
SCOPE.md
Normal file
@@ -0,0 +1,235 @@
|
||||
---
|
||||
domain: infotech
|
||||
repo: sand-boxer
|
||||
updated: "2026-06-22"
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Concern | Owner |
|
||||
|---------|--------|
|
||||
| Workstream, task, and progress state | `state-hub` |
|
||||
| Cron and event-triggered orchestration | `activity-core` |
|
||||
| SSH reverse tunnels and tunnel health | `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`) |
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
- **Status:** bootstrap — repo registered with State Hub; charter written;
|
||||
implementation not started
|
||||
- **Implementation:** ~0% — no CLI, API, profiles, provisioner, or tests in tree
|
||||
- **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` (State Hub bootstrap) in `ready`
|
||||
- **Lineage (external, not yet migrated):** `the-custodian/e2e-framework/`
|
||||
(CUST-WP-0028, completed) and `infra/build-machines/` (CUST-WP-0032)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
Nothing in **this repo** provisions or manages sandboxes yet.
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
---
|
||||
|
||||
## How It Fits
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
- **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)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## 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).
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
Reference in New Issue
Block a user