--- domain: custodian repo: sand-boxer updated: "2026-06-21" --- # INTENT > This file explains why sand-boxer exists, what problem it solves in the > Custodian ecosystem, and where its authority begins and ends. --- ## Why it exists Custodian automation is moving from **workstation-anchored** execution to **Railiance01-scheduled** orchestration. That shift is right for reliability: activity-core on Railiance01 can fire maintenance and coordination jobs on a stable clock. It does not, by itself, give agents a safe place to **develop, build, and test** without the laptop filesystem, sleep cycles, and single-user blast radius. sand-boxer exists to provide **isolated execution environments** — sandboxes — where agentic and deterministic work can run on dedicated infrastructure while remaining observable and governable from State Hub. The goal is progress without requiring the workstation as a runtime: repos are checked out, tools run, tests execute, and artifacts return through controlled channels. The laptop becomes optional for operations, not the hub of all execution. --- ## The governing principle sand-boxer is the **execution isolation and provisioning service** for agentic development and related workloads. It should answer: 1. **Where can this work run safely?** Profile selection (compose stack, VM, future cluster worker) and host placement. 2. **How is isolation enforced?** Networks, TTL, resource limits, teardown, and cleanup guarantees. 3. **How does the sandbox phone home?** Reachability via ops-bridge tunnels and SSH identity via ops-warden — without owning either. 4. **What happened?** Registration, health, and lifecycle events visible to State Hub and reuse-surface consumers. It should not become the scheduler, the work-state database, the connectivity authority, or production application hosting on Railiance01. --- ## Strategic context ### Workstation automation is interim, not the target Local timers and laptop-resident scripts were useful for bootstrapping ADR-001 consistency sync and similar jobs. They are not the long-term substrate. Railiance01-based activity-core schedules are the primary direction; workstation paths remain only where no sandbox or cluster alternative exists yet. ### Railiance01 vs sandbox hosts | Layer | Role | |-------|------| | **Railiance01** | Production k3s, activity-core, Temporal, stable custodian schedules | | **sandboxer01** (or equivalent) | Dedicated VM for dev/agent sandboxes — **isolated blast radius** | | **CoulombCore** | Acceptable interim sandbox host during migration; not a substitute for deliberate isolation from production | | **Workstation (WSL)** | Control plane anchor today; **not** the desired execution surface | sand-boxer owns the **abstraction and lifecycle** of sandboxes. It does not own Railiance01 cluster operations (see `railiance-cluster` / `railiance-apps`). ### Lineage This repository consolidates and generalizes patterns that today live split and unregistered in `the-custodian`: - **E2E sandbox framework** (`e2e-framework/`) — SSH to remote host, isolated directory, docker compose, teardown (`CUST-WP-0028`). - **Build machines** (`infra/build-machines/`) — reproducible VM images, reverse tunnels, State Hub capability registration (`CUST-WP-0032`). sand-boxer extracts a **reusable platform** from those precedents so `the-custodian` can stay governance-focused with a small operational surface. --- ## What it is sand-boxer is the **sandbox provisioning and profile catalog** for Custodian. It is intended to contain: - **Sandbox profiles** — e.g. compose-based e2e stacks, VM images, future container-on-worker patterns - **Provision / wait / teardown** lifecycle — TTL, idempotent cleanup, port and network conventions - **Host placement policy** — which profiles run on sandboxer01, coulombcore interim, or other registered hosts - **CLI and/or API** for operators and agents to request isolated environments - **State Hub registration contract** — extend the `build-agent` self-register pattern to generic sandbox identities - **Capability registry entries** in this repo's `registry/` for federation via reuse-surface (e.g. `capability.execution.sandbox-provision`) - Runbooks, templates (Packer, compose bundles), and tests for the above --- ## What it is not | 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 | | ADR-001 workplan ↔ DB reconciliation | `state-hub` (`consistency_check.py`) | sand-boxer may **consume** connectivity and certificates; it must not duplicate or subsume those authorities. --- ## Intended users - **Human operators (`adm`)** — provision sandboxes, manage profiles and hosts, inspect lifecycle and cleanup - **LLM agents (`agt`)** — request isolated environments for coding, testing, and verification without laptop filesystem dependence - **Deterministic automations (`atm`)** — activity-core instructions and CI hooks that need a bounded execution venue --- ## Design principles - **Blast radius isolation** — sandbox workloads must not jeopardize Railiance01 production stability; prefer dedicated hosts (sandboxer01) for agentic dev - **Profiles over one-offs** — every sandbox type is a named, versioned profile with documented inputs, outputs, and teardown - **Reachability, not ownership** — use ops-bridge for tunnels and ops-warden for SSH identity; sand-boxer orchestrates, it does not issue certs or run tunnel daemons - **Observable lifecycle** — create, ready, active, expired, and destroyed states are attributable and queryable - **Disposable by default** — sandboxes are TTL-bound; persistence is explicit and exceptional - **Registry-first reuse** — register capabilities in this repo and federate through reuse-surface before ad hoc duplication elsewhere --- ## Near-term outcomes A first useful version of sand-boxer should: 1. Define at least one **production-oriented profile** (e.g. compose sandbox on sandboxer01 or coulombcore interim) with documented provision/teardown 2. Register **`capability.execution.sandbox-provision`** (or equivalent) in `registry/` and pass reuse-surface validation 3. Integrate with **ops-bridge** reachability and **State Hub** registration 4. Provide a clear migration path for e2e-framework and build-machines callers 5. Enable activity-core and agents to request sandboxes without workstation repo paths as a hard dependency --- ## Maturity target A mature sand-boxer should be the **standard execution venue** for agentic development in Custodian: Railiance01 decides *when* work runs; sand-boxer decides *where* isolated execution happens; State Hub records *what* changed. The workstation is optional — used for human preference, not as a single point of runtime failure.