From e248f669a38449fe0d80e6245cce267669e6cb25 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 21 Jun 2026 23:04:34 +0200 Subject: [PATCH] docs: add initial INTENT.md for sand-boxer Charter the repo as Custodian execution isolation: sandbox profiles, dedicated hosts (sandboxer01), and migration path from the-custodian e2e-framework and build-machines patterns. --- INTENT.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..e25fa6e --- /dev/null +++ b/INTENT.md @@ -0,0 +1,180 @@ +--- +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. \ No newline at end of file