generated from coulomb/repo-seed
tegwick
f33cff5363
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.
235 lines
9.5 KiB
Markdown
235 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:** ~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` |