tegwick
e248f669a3
Charter the repo as Custodian execution isolation: sandbox profiles, dedicated hosts (sandboxer01), and migration path from the-custodian e2e-framework and build-machines patterns.
7.1 KiB
domain, repo, updated
| domain | repo | updated |
|---|---|---|
| custodian | sand-boxer | 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:
- Where can this work run safely? Profile selection (compose stack, VM, future cluster worker) and host placement.
- How is isolation enforced? Networks, TTL, resource limits, teardown, and cleanup guarantees.
- How does the sandbox phone home? Reachability via ops-bridge tunnels and SSH identity via ops-warden — without owning either.
- 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-agentself-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:
- Define at least one production-oriented profile (e.g. compose sandbox on sandboxer01 or coulombcore interim) with documented provision/teardown
- Register
capability.execution.sandbox-provision(or equivalent) inregistry/and pass reuse-surface validation - Integrate with ops-bridge reachability and State Hub registration
- Provide a clear migration path for e2e-framework and build-machines callers
- 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.