docs(design): plan docker sandbox provider + sandboxes allowlist

[junaway]

Context

Two follow-on design docs for the sandbox axis, built on the seams the sandbox-agent refactor (#5264) extracted, and folding in the docker mode learnings from the persistent-sessions PoC (#4813).

What

• docs/design/agent-workflows/projects/docker-sandbox/docker-sandbox-plan.md — a docker sandbox provider: one container per session on the runner's Docker daemon, parked via docker stop in the existing session pool instead of the PoC's fresh-container-per-turn. Adds what the PoC lacked: a deterministic container naming convention (<runner-container-name>-sandbox-<fingerprint-hash>), agenta.sandbox.* labels as the discovery/GC/re-adoption index, boot + periodic sweeps (the PoC leaked containers), and a durable-cwd recommendation (host bind-mount over per-container FUSE caps).
• docs/design/agent-workflows/projects/allowed-sandboxes/allowed-sandboxes-plan.md — AGENTA_RUNNER_SANDBOXES_ALLOWLIST, a comma-separated per-deployment provider allowlist generalizing AGENTA_SANDBOX_LOCAL_ALLOWED (kept as a deprecated restrictive-wins alias). Enforced at every layer: runner buildRunPlan (authoritative, fail-closed) + buildSandboxProvider backstop, services/oss generalized gate, api RunnerConfig, web __env.js → dropdown filter, hosting/helm. Cloud sets daytona; self-host stays unset (all allowed).
• An addendum on projects/sandbox-agent-refactor/sandbox-agent-refactor-plan.md linking both plans and noting its pre-rename services/agent paths.

Both plans carry an explicit deployment-surface checklist (env *.example files, compose blocks, helm schema/values/helpers/values example, self-host configuration MDX).

Notes

• The drive-by default mismatch found while auditing (AGENTA_SERVICES_CODE_SANDBOX_RUNNER: SDK registry restricted vs documented local) was fixed directly on big-agents in 2d539c653c.
• Docs only; no runtime changes.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 13, 2026 4:42pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 005007bd-5a25-4ab5-a4a6-4a3aab80fb8f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/docker-sandbox-and-sandboxes-allowlist

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds two new design-plan documents that extend the sandbox provider “axis” (introducing a proposed docker provider and a cross-layer sandbox allowlist), and links them back to the earlier sandbox-agent refactor plan so future implementation work has a clear roadmap and seam references.

Changes:

• Added a detailed plan for a docker sandbox provider (per-session containers, naming/labels, GC, keep-alive/pooling, and deployment surface considerations).
• Added a plan for AGENTA_RUNNER_SANDBOXES_ALLOWLIST to gate allowed sandbox providers across runner/services/api/web/hosting, with clear precedence vs. AGENTA_SANDBOX_LOCAL_ALLOWED.
• Updated the sandbox-agent refactor plan with an addendum linking to these follow-on plans and noting the services/agent → services/runner rename.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/design/agent-workflows/projects/sandbox-agent-refactor/sandbox-agent-refactor-plan.md	Adds an addendum linking the refactor seams to the new docker/allowlist follow-on plans and clarifying path rename context.
docs/design/agent-workflows/projects/docker-sandbox/docker-sandbox-plan.md	New design plan for a docker sandbox provider, including lifecycle, naming/labels, GC, durable cwd options, and testing slices.
docs/design/agent-workflows/projects/allowed-sandboxes/allowed-sandboxes-plan.md	New design plan for a deployment-level sandbox provider allowlist enforced consistently across layers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.