generated from coulomb/repo-seed
tegwick
c0a9261cdc
Add profile.sandbox-canary, HostSnapshot/inventory/stale schemas, SSH collectors, before/after provision deltas, telemetry export to State Hub and local JSON, default `sandboxer create` self-deploy, inspect/reap-stale CLI, runbook, and CoulombCore verification (26 tests pass).
236 lines
9.5 KiB
Markdown
236 lines
9.5 KiB
Markdown
---
|
||
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:** 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)
|
||
|
||
---
|
||
|
||
## 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` |