coulomb/sand-boxer
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add workplans SAND-WP-0010–0012 for remaining gaps

Browse Source 
Cloud adapters (E2B/Modal/BYOK/fin-hub), reachability and consumer
profiles, Packer orchestration; update gap analysis and SCOPE.
This commit is contained in:
Bernd Worsch
2026-06-24 12:47:08 +02:00
parent 151fc41299
commit 5466330cf4
7 changed files with 405 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
SCOPE.md
View File

@@ -116,8 +116,8 @@ own tunnels or CAs.
- **Status:** v0 operational — self-hosted compose path proven on CoulombCore;
routing, payments stub, and snapshots shipped
- **Workplans finished:** SAND-WP-0001–0008 (all workplans in `workplans/`;
0003/0004 delivered in sibling repos wise-validator / the-custodian)
- **Workplans finished:** SAND-WP-0001–0009 (0003/0004 in sibling repos)
- **Workplans ready:** SAND-WP-0010–0012 (cloud, consumers, Packer)
- **Package:** `src/sandboxer/` — CLI, manager, extensions, routing, payments,
snapshots, telemetry, HTTP API
- **Profiles:** `profile.compose-e2e`, `profile.compose-checkpoint`,
@@ -133,7 +133,9 @@ own tunnels or CAs.
`make e2e REPO=` shim (SAND-WP-0004)
Latest gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
Latest workplan: **SAND-WP-0009** (TTL enforcement — finished).
Gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
**Ready workplans:** SAND-WP-0010 (cloud adapters), 0011 (consumer profiles),
0012 (Packer orchestration).
---
@@ -172,14 +174,15 @@ cd ~/the-custodian && make e2e REPO=activity-core
## What Is Not Possible Yet
- ~~TTL auto-expiry / `extend_ttl` enforcement~~ — done (SAND-WP-0009)
- Packer build orchestration from `create` (attach-only today)
- Real E2B / Modal / Daytona adapters (in-repo stub only)
- Packer build orchestration from `create` — **SAND-WP-0012**
- Real E2B / Modal adapters (stub today) — **SAND-WP-0010**
- Consumer profiles (agent-dev, build) — **SAND-WP-0011**
- Cross-host snapshot transfer
- Formal ops-bridge tunnel attachment in reachability descriptor
- Formal ops-bridge tunnel attachment — **SAND-WP-0011**
- Dedicated sandboxer01 host (CoulombCore interim only today)
- `reuse-surface validate` / federation publish workflow
- ~~`.repo-classification.yaml`~~ — done (SAND-WP-0009)
- fin-hub billing export for metered usage
- fin-hub billing export — **SAND-WP-0010**
---

4
docs/migration-gaps.md
View File

@@ -44,6 +44,8 @@ Deferred: Packer orchestration from API, `make remote-build` shim.
| Item | Workplan |
|------|----------|
| ~~SaaS extensions + payments v0~~ | SAND-WP-0006 — stub + routing + credits |
| E2B / Modal real adapters | Post SAND-WP-0006 |
| E2B / Modal real adapters + fin-hub | **SAND-WP-0010** |
| Consumer profiles + reachability | **SAND-WP-0011** |
| Packer orchestration + remote-build shim | **SAND-WP-0012** |
| ~~Snapshot / restore~~ | SAND-WP-0007 — `docs/snapshots.md` |
| ~~TTL enforcement + scheduled reap~~ | SAND-WP-0009 — `docs/ttl.md` |

33
history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md
View File

@@ -160,14 +160,14 @@ some sibling sign-offs sit outside this repo.
| Prio | Gap | Owner | Proposed track |
| --- | --- | --- | --- |
| **P1** | TTL enforcement + `extend_ttl` + `expires_at` | sand-boxer | **SAND-WP-0009** |
| **P2** | TTL reap scheduler / activity-core contract | sand-boxer + activity-core | **SAND-WP-0009** |
| **P3** | `.repo-classification.yaml` + registry refresh | sand-boxer | **SAND-WP-0009** |
| **P4** | HTTP API parity (`recreate`, `extend_ttl`) | sand-boxer | **SAND-WP-0009** |
| **P5** | Real E2B / Modal adapters + BYOK | sand-boxer | SAND-WP-0010 |
| **P6** | ops-bridge tunnel in reachability descriptor | sand-boxer | SAND-WP-0011 |
| **P7** | Consumer profiles (glas-harness, snuggle) | sand-boxer | SAND-WP-0011 |
| **P8** | Packer build orchestration + remote-build shim | sand-boxer | SAND-WP-0012 (WP-0005-T06) |
| ~~**P1**~~ | TTL enforcement + `extend_ttl` + `expires_at` | sand-boxer | **SAND-WP-0009** — done |
| ~~**P2**~~ | TTL reap / activity-core contract | sand-boxer | **SAND-WP-0009** — `docs/integrations/activity-core.md` |
| ~~**P3**~~ | `.repo-classification.yaml` + registry refresh | sand-boxer | **SAND-WP-0009** — done |
| ~~**P4**~~ | HTTP API parity (`recreate`, `extend_ttl`) | sand-boxer | **SAND-WP-0009** — done |
| **P5** | Real E2B / Modal adapters + BYOK | sand-boxer | **SAND-WP-0010** |
| **P6** | ops-bridge tunnel in reachability descriptor | sand-boxer | **SAND-WP-0011** |
| **P7** | Consumer profiles (glas-harness, snuggle) | sand-boxer | **SAND-WP-0011** |
| **P8** | Packer build orchestration + remote-build shim | sand-boxer | **SAND-WP-0012** |
| **P9** | Cross-host snapshot transfer | sand-boxer | Future |
| **P10** | fin-hub billing export | sand-boxer + platform | With SAND-WP-0010 |
| **P11** | sandboxer01 dedicated host | infra / operator | Outside repo |
@@ -175,16 +175,17 @@ some sibling sign-offs sit outside this repo.
---
## 9. Recommended next workplan
## 9. Recommended workplans (2026-06-24)
**SAND-WP-0009 — TTL enforcement and operational hardening**
| Workplan | Status | Closes |
| --- | --- | --- |
| SAND-WP-0009 | **finished** | P1–P4 (TTL, hygiene, HTTP parity) |
| SAND-WP-0010 | ready | P5, P10 (E2B/Modal, BYOK, fin-hub) |
| SAND-WP-0011 | ready | P6, P7 (reachability, consumer profiles) |
| SAND-WP-0012 | ready | P8 (Packer orchestration, remote-build shim) |
Closes P1–P4: the largest functional gap (disposable-by-default TTL), platform
hygiene (classification, registry), and HTTP parity. Unblocks activity-core
scheduling of expire/reap without implementing activity-core itself.
Subsequent: **SAND-WP-0010** (real cloud adapters), **SAND-WP-0011**
(reachability + consumer profiles), **SAND-WP-0012** (Packer orchestration).
**Suggested implementation order:** 0010 and 0011 may parallelize; 0012 depends
on stable vm-packer attach (done). Operator tracks P11/P12 outside repo.
---

3
workplans/SAND-WP-0009-ttl-and-operational-hardening.md
View File

@@ -21,8 +21,7 @@ registry, HTTP parity).
Gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
**Predecessor:** SAND-WP-0007 (snapshots — finished)
**Follow-on:** SAND-WP-0010 (real cloud adapters), SAND-WP-0011 (reachability +
consumer profiles), SAND-WP-0012 (Packer orchestration)
**Follow-on:** SAND-WP-0010, SAND-WP-0011, SAND-WP-0012 (workplans filed 2026-06-24)
---

129
workplans/SAND-WP-0010-cloud-adapters-and-billing.md Normal file
View File

@@ -0,0 +1,129 @@
---
id: SAND-WP-0010
type: workplan
title: "Cloud adapters and billing export"
domain: infotech
repo: sand-boxer
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-24"
updated: "2026-06-24"
---
# Cloud adapters and billing export
Replace `ext.saas-stub` with real metered cloud backends (E2B, Modal) and wire
BYOK credential routing plus fin-hub billing export.
Gap analysis P5/P10: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
Carries forward: SAND-WP-0006-T06 (deferred)
**Predecessor:** SAND-WP-0009 (TTL — finished)
**Follow-on:** SAND-WP-0011 (reachability + consumer profiles)
---
## Credential routing and BYOK
```task
id: SAND-WP-0010-T01
status: todo
priority: high
```
Document provider key paths via `warden route find` (OpenBao custody — never in
Git). Extension config `secret_ref` fields; loader resolves at provision time
into env/handle only (not persisted on `SandboxStatus`). Docs: `docs/payments.md`
BYOK section.
## ext.e2b adapter
```task
id: SAND-WP-0010-T02
status: todo
priority: high
```
`extensions/ext.e2b.yaml`, `sandboxer.extensions.e2b:E2BExtension` — provision,
`wait_ready`, `teardown`, `estimate_cost`, `meter_actual`. Profile
`profile.e2b-burst` with `pricing_model: metered`. Unit tests with mocked HTTP
client (no live API in CI).
## ext.modal adapter
```task
id: SAND-WP-0010-T03
status: todo
priority: high
```
`extensions/ext.modal.yaml`, `sandboxer.extensions.modal:ModalExtension` —
same contract as E2B. Profile `profile.modal-gpu` (or shared burst profile with
routing). Mocked tests.
## Routing and credits integration
```task
id: SAND-WP-0010-T04
status: todo
priority: high
```
Update `profile.burst-sandbox` route list to prefer real adapters when credentials
present; fall back to `ext.saas-stub`. Pre-create balance check and post-destroy
debit unchanged. Emit meter events with `extension_id` discriminator.
## fin-hub billing export
```task
id: SAND-WP-0010-T05
status: todo
priority: medium
```
On metered destroy, optional export hook (`SANDBOXER_FIN_HUB_URL` or disabled by
default) posting usage record (sandbox_id, extension_id, duration_s, actual_usd).
Stub/mock in tests; operator runbook for railiance-platform path.
## Docs and capability registry
```task
id: SAND-WP-0010-T06
status: todo
priority: medium
```
`docs/cloud-adapters.md`, runbook per provider, registry maturity bump (A5/C5
when adapters ship). Update `SCOPE.md`, `docs/routing.md`.
## Tests and smoke
```task
id: SAND-WP-0010-T07
status: todo
priority: high
```
`tests/test_e2b.py`, `tests/test_modal.py`, routing fallback tests. Optional
operator smoke script (gated on credentials, not CI). `make check` green.
---
## Out of scope
| Item | Track |
|------|-------|
| Coulomb-native runtime (phase 5) | Backlog |
| Daytona OSS adapter | Future WP |
| Cross-host snapshot transfer | Future |
---
## Acceptance criteria
- At least one real cloud adapter provisions/teardown via CLI with mocked CI
- BYOK documented; no secrets in repo or State Hub payloads
- `profile.burst-sandbox` routes to real adapter when creds available
- fin-hub export hook callable (stub OK in v0)
- SAND-WP-0006-T06 superseded; cancel or mark done when complete

129
workplans/SAND-WP-0011-reachability-and-consumer-profiles.md Normal file
View File

@@ -0,0 +1,129 @@
---
id: SAND-WP-0011
type: workplan
title: "Reachability and consumer profiles"
domain: infotech
repo: sand-boxer
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-24"
updated: "2026-06-24"
---
# Reachability and consumer profiles
Formalize ops-bridge tunnel attachment in reachability descriptors and ship
first-class profiles for glas-harness and snuggle-inventor consumers.
Gap analysis P6/P7: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
**Predecessor:** SAND-WP-0010 (cloud adapters — proposed)
**Follow-on:** SAND-WP-0012 (Packer orchestration)
Note: Can proceed in parallel with SAND-WP-0010 where profiles are self-hosted.
---
## Reachability descriptor enrichment
```task
id: SAND-WP-0011-T01
status: todo
priority: high
```
Extend `Reachability` model: optional `tunnel` (local port / alias), `tunnel_via`
(ops-bridge route id), `identity` (warden actor hint). Populate from profile
`reachability` spec + `SANDBOXER_TUNNEL_*` env on compose-ssh / vm-packer.
Document contract in `docs/meta-framework.md`; sand-boxer does not own tunnels.
## ops-bridge integration helper
```task
id: SAND-WP-0011-T02
status: todo
priority: medium
```
Optional `sandboxer reachability show <id>` (or enrich `get` output) surfacing
SSH one-liner and tunnel status pointer (`ops-bridge` MCP / CLI doc link). No
tunnel bring-up in sand-boxer — pointer only.
## profile.agent-dev
```task
id: SAND-WP-0011-T03
status: todo
priority: high
```
Profile for glas-harness: longer TTL defaults, `actor: agt` examples, route
`prefer-self-hosted`. Extension `ext.compose-ssh` or vm-packer attach variant.
Update `docs/integrations/glas-harness.md` with real profile id.
## profile.build (snuggle-inventor)
```task
id: SAND-WP-0011-T04
status: todo
priority: high
```
Build sandbox profile binding `profile.vm-haskell-build` or compose path;
`setup.instructions` placeholder; `secret_refs` list on profile (resolution v0:
validate refs exist via `warden route`, inject at provision boundary only).
Update `docs/integrations/snuggle-inventor.md`.
## Secret boundary v0
```task
id: SAND-WP-0011-T05
status: todo
priority: medium
```
`SetupSpec.secret_refs` resolution in manager pre-provision hook: fetch via
operator-documented OpenBao path; pass to extension handle; never store on
`SandboxStatus` or emit to State Hub. Tests with mocked resolver.
## Consumer smoke scripts
```task
id: SAND-WP-0011-T06
status: todo
priority: medium
```
`scripts/smoke-agent-dev.sh`, `scripts/smoke-build-profile.sh` (dry-run or
CoulombCore gated). Integration section in each consumer doc.
## Tests and docs
```task
id: SAND-WP-0011-T07
status: todo
priority: high
```
Model tests for reachability fields; profile loader tests; update `SCOPE.md`
profile catalog. `make check` green.
---
## Out of scope
| Item | Track |
|------|-------|
| glas-harness tool execution | glas-harness repo |
| snuggle code generation | snuggle-inventor repo |
| ops-bridge tunnel automation | ops-bridge repo |
---
## Acceptance criteria
- `profile.agent-dev` and `profile.build` load and create via CLI
- Reachability JSON includes tunnel metadata when profile declares ops-bridge
- secret_refs resolved at boundary; absent from agent-visible status payload
- Consumer integration docs reference real profile ids

116
workplans/SAND-WP-0012-packer-orchestration.md Normal file
View File

@@ -0,0 +1,116 @@
---
id: SAND-WP-0012
type: workplan
title: "Packer build orchestration"
domain: infotech
repo: sand-boxer
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-24"
updated: "2026-06-24"
---
# Packer build orchestration
Trigger Packer builds from `sandboxer create` and ship the-custodian
`make remote-build` shim — completing the build-machines migration arc.
Gap analysis P8: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md`
Carries forward: SAND-WP-0005-T06 (deferred)
**Predecessor:** SAND-WP-0011 (consumer profiles — proposed; attach mode done)
**Follow-on:** reuse-surface federation publish; sandboxer01 operator track
---
## Packer build mode on ext.vm-packer
```task
id: SAND-WP-0012-T01
status: todo
priority: high
```
Extend `VMPackerExtension` with optional `build` mode: inputs `packer_template`,
`vm_name` trigger local/SSH Packer run per the-custodian
`infra/build-machines/` conventions. Distinct from attach mode; teardown does not
destroy VM image. Tests mocked subprocess.
## profile.vm-packer-build
```task
id: SAND-WP-0012-T02
status: todo
priority: high
```
New profile binding build mode with placement and TTL suitable for long builds.
Document inputs in `docs/migration-build-machines.md`.
## Manager and CLI integration
```task
id: SAND-WP-0012-T03
status: todo
priority: high
```
`create` path selects build vs attach via profile or `inputs.mode=build|attach`.
Progress events to State Hub during long provision. CLI help text.
## the-custodian remote-build shim
```task
id: SAND-WP-0012-T04
status: todo
priority: medium
```
In `the-custodian`: `make remote-build PROJECT=` delegates to
`sandboxer create --profile profile.vm-haskell-build` (attach) or new build
profile. Deprecation notice on legacy rsync-only path. Verification script
mirroring SAND-WP-0004 e2e shim pattern.
## Port-registry automation
```task
id: SAND-WP-0012-T05
status: todo
priority: low
```
Optional helper: register tunnel port from build-machines port-registry when VM
attach provisions (read-only or emit ops-bridge config snippet). Document only
if full automation deferred.
## Docs, tests, runbook
```task
id: SAND-WP-0012-T06
status: todo
priority: high
```
Update `docs/migration-build-machines.md`, `docs/extension-sdk.md`, operator
runbook under `docs/runbooks/`. `tests/test_vm_packer.py` build mode cases.
`make check` green.
---
## Out of scope
| Item | Track |
|------|-------|
| OVA import on hypervisor | Operator / build-machines |
| systemd build-agent changes | the-custodian infra |
| sandboxer01 host | Infra operator |
---
## Acceptance criteria
- Build mode provisions via CLI with mocked Packer in CI
- Attach mode unchanged (backward compatible)
- the-custodian shim documented and verified
- SAND-WP-0005-T06 superseded when complete