feat: execution sandbox — per-thread hard isolation for the agent workspace (opt-in)

[blove]

What

An opt-in execution sandbox: each Agent-Protocol conversation thread gets a hard-isolated workspace — filesystem, shell, and network — via a provider-agnostic SandboxProvider contract with a Docker reference implementation. Complements tool scoping (#261): scoping limits which tools the model may name; the sandbox bounds what an allowed tool can actually do.

Spec: docs/superpowers/specs/2026-06-25-execution-sandbox-design.md · Plan: docs/superpowers/plans/2026-06-25-execution-sandbox.md · Docs page: /docs/sandbox

// dawn.config.ts — new typed config() helper included
import { config } from "@dawn-ai/cli"
import { dockerSandbox } from "@dawn-ai/sandbox"

export default config({
  sandbox: {
    provider: dockerSandbox({ image: "node:22-slim" }),
    network: { mode: "allow", denylist: ["169.254.169.254"] },
    resources: { memoryMb: 512, cpus: 1 },
  },
})

No sandbox key → zero behavior change.

How

• Contract types (SandboxProvider/SandboxHandle/SandboxPolicy/SandboxConfig) in @dawn-ai/workspace — the handle's filesystem/exec implement the existing backend interfaces, so the workspace capability consumes them unchanged.
• SandboxManager (cli, per-server singleton): per-thread acquire/reuse with concurrent-acquire dedup, idle reaper (release keeps the volume), thread DELETE → destroy (volume too), shutdown → release-all.
• Runtime wiring: threadId threaded into route prep; when configured, the workspace capability + offload store get the thread's sandbox backends and in-sandbox workspaceRoot. Subagents share the parent thread's sandbox via a dedicated sandboxThreadId key (deliberately decoupled from LangGraph's checkpoint thread_id).
• dockerSandbox (new @dawn-ai/sandbox pkg): persistent per-thread container + named volume (create-or-reattach → workspace survives turns, restarts, container crashes), clean env (host env never inherited), --memory/--cpus caps, deny → --network none (exact).
• dawn check validates the config + runs provider.preflight() (e.g. Docker daemon reachable).
• Isolation correctness: the materialized-agent cache is bypassed when sandboxed (same remedy as the subagent task-tool precedent) so tools bind per-thread — caught by the wiring e2e, which found and killed a real cross-thread leak during development. A separately-bisected checkpoint-identity regression in subagent dispatch was also fixed (sandboxThreadId decoupling).

Testing

• Docker-free in validate: fakeSandbox (in-memory provider) + a provider conformance kit + SandboxManager lifecycle units + a behavioral wiring e2e (writes route into the sandbox, persist across turns, host fs untouched, per-thread isolation — false-green-verified both ways).
• Gated sandbox-docker CI job (new, independent lane): the conformance kit against real Docker + deny-network egress block + host-fs-untouched + release→reacquire volume durability. This PR's run is the authoritative real-Docker proof (local daemon here can't pull images).
• Full local verification: lint/build/typecheck green; pnpm test 976 passing (the one failure found during verification was bisected and fixed on this branch); check-docs green; Verdaccio publish harness green including the new package.

Honest scope (also in the docs page)

Docker's boundary, not a microVM — the seam is provider-agnostic so a gVisor/Kata/cloud-microVM provider is the stronger drop-in for hostile-grade multi-tenant. allow-mode denylist is best-effort in the Docker reference (deny is exact). The sandbox protects the host and other tenants; it does not prevent an agent exfiltrating its own sandbox's data under allow mode.

Release notes

• Changeset is patch (fixed-group 0.x: a minor would force 1.0.0 — the chore(release): downgrade tool-scoping changeset to patch (release 0.8.3, not 1.0.0) #268 precedent).
• @dawn-ai/sandbox is a first publish → needs the one-time manual OIDC bootstrap + trusted-publishing config at release time (same as @dawn-ai/memory at 0.8.3).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dawnai	Ready	Preview, Comment	Jul 6, 2026 4:22am

[github-actions]

Automated approval: this PR received an intelligent (AI) code review. See the review comments on this PR.

[github-actions]

Claude finished @blove's task in 4m 24s —— View job

---

PR Review: feat/execution-sandbox

• Gather context
• Read changed files
• Analyze for correctness bugs, security issues, type-safety, test coverage
• Post findings

---

The overall architecture is solid — the SandboxProvider/SandboxHandle contract is clean, the Docker reference implementation is straightforward, and the sandbox-bypass of the materialized-agent cache (to prevent cross-thread tool reuse) is the right call. The conformance kit + fakeSandbox testing strategy is well-structured. The sandboxThreadId decoupling from thread_id is a subtle but correct design.

Found 4 correctness/security issues and 1 minor concern:

Security

• docker-exec.ts:13 — Env key is interpolated unsanitized into sh -c. Only the value is shellQuoted; a key containing ;, &&, or $ can inject shell commands. Validate keys against [A-Za-z_][A-Za-z0-9_]*.

Correctness

• sandbox-manager.ts:37–61 — inUse counter only tracks the acquiring phase, not active turns. Once a handle is returned from cache, inUse is 0. The idle reaper can fire and release() a container that is still mid-turn if the turn takes longer than idleTimeoutMs (default 10 min).
• docker-filesystem.ts:26 — writeFile uses cat > path which fails if the parent directory doesn't exist inside the container. The host localFilesystem presumably creates parent dirs; this behavioral difference will cause unexpected failures when agents write to sub-paths.
• runtime-server.ts:129 — Shutdown calls sandboxManager.releaseAll() (removing containers) before draining in-flight requests. Mid-turn requests that don't immediately honour the abort signal will encounter a removed container and get opaque docker exec errors instead of a clean abort.

Feature gap

• execute-route.ts:500 — buildOffload checks existsSync(join(appRoot, "workspace")) on the host. There is no host workspace/ dir when sandboxed, so tool-output offloading is silently disabled for all sandboxed routes. Pass sandboxWorkspaceRoot to buildOffload to enable it.

Minor

• docker-sandbox.ts:7 — The sanitize function maps all non-alphanumeric chars to _, so t/1 and t_1 collide to the same container name. Harmless with UUID thread IDs but fragile by design; a short hex digest would be collision-free.

[github-actions]

Claude finished @blove's task in 4m 42s —— View job

---

PR Review: feat/execution-sandbox

• Gather context
• Read changed files
• Verify status of previously-flagged issues
• Check for new issues (correctness, security, type-safety, test coverage)
• Post findings

---

The architecture is solid and the core isolation contract is clean. Three of the five issues from the previous review are confirmed fixed:

• ✅ docker-exec.ts — env key validation added (/^[A-Za-z_][A-Za-z0-9_]*$/)
• ✅ docker-filesystem.ts — writeFile now runs mkdir -p "$(dirname ...)" before cat >
• ✅ runtime-server.ts (listener) — releaseAll is correctly sequenced after the in-flight request drain inside createRuntimeRequestListener.close()

Two prior issues remain open, and one new correctness bug was found:

Still open from prior review

• sandbox-manager.ts:36–61 — The cache-hit path in getForThread updates lastUsedAt at turn start but does not increment inUse. The idle reaper's guard (entry.inUse > 0) is therefore false for any active turn that came from cache. Turns longer than idleTimeoutMs (default 10 min) will have their container reaped mid-turn.

• execute-route.ts:500–504 — buildOffload checks existsSync(join(appRoot, "workspace")) on the host. There is no host workspace/ dir when sandboxed, so offloading is silently disabled for all sandboxed routes. sandboxWorkspaceRoot is already available at the call site and just needs to be threaded in.

New issue

• runtime-server.ts:144–151 — startRuntimeServer (the production path) destructures only { listener, state, shutdownController } from createRuntimeRequestListener, discarding its close function. startRuntimeServer.close() never clears the sandbox reaper interval or calls sandboxManager.releaseAll() — both are scoped inside createRuntimeRequestListener and unreachable. All sandbox containers leak on every production server shutdown. The createRuntimeRequestListener.close() path with the correct drain-then-release sequencing is only reachable from tests.

The sanitize collision minor (docker-sandbox.ts:7) acknowledged from the prior review remains; it's low-risk with UUID thread IDs.

[github-actions]

Claude finished @blove's task in 2m 55s —— View job

---

PR Review: feat/execution-sandbox

• Gather context
• Read changed files (sandbox-manager, runtime-server, execute-route, docker files)
• Verify status of previously-flagged issues
• Check for new issues
• Post findings

---

Three of the five issues from prior reviews are confirmed fixed:

• ✅ docker-exec.ts — env key validation against /^[A-Za-z_][A-Za-z0-9_]*$/ added
• ✅ docker-filesystem.ts — writeFile now runs mkdir -p "$(dirname ...)" before cat >
• ✅ runtime-server.ts — startRuntimeServer now destructures close: listenerClose and calls await listenerClose(), correctly routing production shutdown through the drain-then-releaseAll sequence (the issue flagged as new in the second review is fixed)

Two issues remain open:

sandbox-manager.ts:38–42 — inUse counter not incremented in cache-hit or concurrent-dedup paths. After the first acquisition completes (and finally() drops inUse to 0), every subsequent cached turn runs with inUse === 0. The reaper guard entry.inUse > 0 || entry.acquiring is false for all cached turns, so any turn longer than idleTimeoutMs (10 min default) can have its container released mid-turn. The existing test only covers the still-acquiring case. See inline comment for the [handle, done] fix.

execute-route.ts:500–505 — buildOffload still checks existsSync(join(appRoot, "workspace")) on the host. There is no host workspace/ dir when sandboxed, so buildOffload always returns undefined and offloading is silently disabled for all sandboxed routes. sandboxWorkspaceRoot is available at line 497 and just needs to be threaded in as a fifth arg. See inline comment.

The sanitize collision minor (docker-sandbox.ts:7) from the prior review is low-risk with UUID thread IDs and is acknowledged as a known limitation.