Files

tegwick 952cebf2e9 feat: snapshot/restore checkpoints (SAND-WP-0007)

Add workspace checkpoint API with SnapshotStore, extension hooks on
compose-ssh and saas-stub, manager orchestration, CLI/HTTP surface,
profile.compose-checkpoint, and docs/tests.

2026-06-24 07:57:40 +02:00

7.5 KiB

Raw Blame History

domain, repo, updated

domain	repo	updated
infotech	sand-boxer	2026-06-24

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not.

One-liner

Coulomb meta-framework for establishing sandboxes — profile-based provision, extension routing, lifecycle registration, and host telemetry — so agents and automations run in isolated venues without workstation blast radius.

Core Idea

sand-boxer is the sandbox establishment service (OpenRouter for sandboxes). It answers which recipe applies, which backend fulfills it, where it runs, and what happened during lifecycle. It is self-sustained — it does not depend on wise-validator or other sibling projects.

A profile is a named, versioned recipe bound to an extension (backend adapter). Consumers request create; sand-boxer provisions on a placement host, confirms reachability (ready), emits State Hub lifecycle events, and tears down on destroy or operator reap.

wise-validator (separate repo) consumes sand-boxer for cross-repo e2e validation; sand-boxer does not run health checks or test commands.

Lineage: provision/teardown extracted from the-custodian/e2e-framework/; infra/build-machines/ remains future ext.vm-packer work.

In Scope

Unified establishment API — CLI v0 + HTTP stub (create, get, list, destroy, recreate, snapshot, restore); extend_ttl planned
Profile catalog — profile.compose-e2e, profile.compose-checkpoint, profile.sandbox-canary; more profiles and extensions over time
Extension platform — ext.compose-ssh (SSH + compose); plugin contract in docs/meta-framework.md
Host placement — profile placement + SANDBOXER_HOST overrides; sandboxer01 preferred, CoulombCore interim
Lifecycle + State Hub — transitions emit progress events; JSON store at ~/.local/share/sandboxer/sandboxes.json
Host telemetry — canary self-deploy, inspect host / inspect stale, reap-stale (SAND-WP-0008)
Capability registry — capability.execution.sandbox-provision (draft)
Sibling integration contracts — docs/integrations/ (glas-harness, wise-validator, snuggle-inventor)
Runbooks and smoke — compose-e2e, sandbox-canary; remote smoke scripts
Workplans and charter — ADR-001 files in workplans/, INTENT.md

Out of Scope

Concern	Owner
E2e health checks, test execution, validation results	wise-validator
Agent gateway, tools, memory	glas-harness
Code generation, tech specs	snuggle-inventor
Workstream / task state	`state-hub`
Scheduling	`activity-core`
SSH tunnels	`ops-bridge`
SSH certificate issuance	`ops-warden`
Canon and agent instruction canon	`the-custodian`
Capability federation hub	`reuse-surface`
Production on Railiance01	`railiance-apps` / domain repos
SaaS sandbox metering / payments	Future SAND-WP-0006

sand-boxer consumes ops-bridge and ops-warden for reachability; it does not own tunnels or CAs.

Relevant When

Provisioning an isolated compose stack on CoulombCore / sandboxer01
Canary self-deploy or host inventory before placing workloads
activity-core, CI, glas-harness, or wise-validator need a sandbox handle
Discovering sandbox capability via registry/
Migrating off the-custodian/e2e-framework provision path

Not Relevant When

Running repo e2e tests end-to-end (use wise-validator validate run)
Local-only work with acceptable blast radius
Tunnel or cert operations alone (ops-bridge / ops-warden)
Task/workstream tracking alone (state-hub)

Current State

Status: v0 operational — self-hosted compose path proven on CoulombCore
Workplans finished: SAND-WP-0001–0005, 0008 (see workplans/)
Package: src/sandboxer/ — CLI, manager, extensions, telemetry, HTTP API
Profiles: profile.compose-e2e, profile.sandbox-canary, profile.vm-haskell-build
Extensions: ext.compose-ssh, ext.vm-packer, ext.saas-stub (metered)
Routing + payments: docs/routing.md, docs/payments.md, sandboxer credits
Registry: capability.execution.sandbox-provision indexed (draft)
Tests: 26 pytest cases; make check green
Sibling: wise-validator ships validate run (SAND-WP-0003)

Latest gap analysis: history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md

What Is Possible Now

make setup && make install          # sandboxer CLI
sandboxer create                    # canary self-deploy (no args)
sandboxer create --profile profile.compose-e2e --input repo=/path/to/repo
sandboxer destroy <id>
sandboxer inspect host / inspect stale / reap-stale
make smoke-remote                   # CoulombCore compose smoke (SANDBOXER_HOST)

# Full e2e validation (wise-validator, separate install):
validate run ~/activity-core

# Legacy operator entry (the-custodian):
cd ~/the-custodian && make e2e REPO=activity-core

State Hub lifecycle events on create/destroy (when hub reachable)
HTTP API via uvicorn sandboxer.api.app:app
Operator runbooks under docs/runbooks/

What Is Not Possible Yet

~~make e2e REPO= shim~~ — done (SAND-WP-0004; delegates to validate run)
TTL auto-expiry / extend_ttl enforcement
~~ext.vm-packer attach mode~~ — done (SAND-WP-0005); Packer build orchestration deferred
Real E2B / Modal adapters (stub + payments v0 done in SAND-WP-0006)
~~Snapshot / restore / checkpoint profiles~~ — done (SAND-WP-0007)
Formal ops-bridge tunnel attachment in reachability descriptor
Dedicated sandboxer01 host (CoulombCore interim only today)
reuse-surface validate / federation publish workflow
.repo-classification.yaml (State Hub C-24 hygiene)

How It Fits

flowchart LR
  WV[wise-validator] -->|create/destroy| SB[sand-boxer]
  GH[glas-harness] -->|create| SB
  AC[activity-core] -->|when| WV
  AC -->|venue request| SB
  SB -->|provision| HOST[CoulombCore / sandboxer01]
  SB -->|lifecycle| SH[state-hub]
  SB -->|SSH reachability| OB[ops-bridge]
  TC[the-custodian e2e-framework] -.->|migrate| WV
  TC -.->|provision migrate| SB

Terminology

Profile — named sandbox recipe (extension binding, placement, TTL metadata)
Extension — backend adapter (provision, wait_ready, teardown)
Establishment — create through ready (distinct from validation pass/fail)
Canary — profile.sandbox-canary self-deploy with host telemetry
Actor types: adm, agt, atm

wise-validator — validation orchestration; one-way consumer of sand-boxer
the-custodian — legacy e2e-framework/; shim migration pending
ops-bridge / ops-warden — connectivity and identity consumers
state-hub — lifecycle visibility
reuse-surface — capability federation target

Provided Capabilities

Registered (draft): capability.execution.sandbox-provision — see registry/capabilities/execution.sandbox-provision.md.

Getting Oriented

Path	Purpose
`INTENT.md`	Charter and sibling boundaries
`docs/meta-framework.md`	API, lifecycle, extension contract
`docs/host-telemetry.md`	Canary and inventory
`docs/migration-gaps.md`	Legacy cutover status
`docs/integrations/`	Consumer contracts
`workplans/`	ADR-001 work structure
`history/`	INTENT ↔ SCOPE assessments
`AGENTS.md`	Session protocol

7.5 KiB Raw Blame History Unescape Escape