generated from coulomb/repo-seed
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.
This commit is contained in:
180
INTENT.md
Normal file
180
INTENT.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user