generated from coulomb/repo-seed
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.
180 lines
7.1 KiB
Markdown
180 lines
7.1 KiB
Markdown
---
|
|
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. |