Repository navigation
Description
Summary
Add a provider-neutral Concepts page for sandboxes under fern/versions/latest/pages/about/concepts/ (e.g. concepts/sandboxes.mdx) that owns the why/what of sandboxes, distinct from the how-to/reference content in infrastructure/sandbox/.
Why now
Sandbox conceptual content is currently a single paragraph spread across about/concepts/environments.mdx (runtime vs sandbox definition) and about/concepts/evaluation.mdx (sandbox as state), with no single canonical home. With multiple providers now landing — OpenSandbox (in main), plus Daytona (#1513), ECS Fargate (#1645), and Apptainer (#1688) in flight under epic #1685 — there are now genuinely different isolation models to explain, which is the conceptual surface that justifies a dedicated page.
This complements the new how-to/reference guide added in PR #1717; that PR covers how to use the API, while this issue covers what sandboxes are and why.
Scope (provider-neutral)
- runtime vs sandbox vs provider — clear three-way distinction (runtime = execution infra; sandbox = runtime with isolated execution; provider = the adapter onto a runtime/backend). Align vocabulary used by the infrastructure guide.
- Isolation / security model — what "isolated execution" actually buys you and why it matters when agents run arbitrary code.
- Lifecycle / state semantics — per-episode vs persistent sandboxes, TTL, snapshots.
- Decision framing — "which kind of sandbox/provider for which situation" (local dev vs cluster vs cloud vs HPC), without duplicating per-provider setup docs.
Out of scope
- Per-provider setup/config (lives in
infrastructure/sandbox/<provider>.mdx). - The sandbox API usage/reference itself (PR [codex] Add sandbox API docs guide #1717).
Implementation notes
- Move/condense the runtime-vs-sandbox definition out of
about/concepts/environments.mdxinto the new page and leave a one-line pointer behind, so there is a single canonical source. - Cross-link: concept page <->
infrastructure/sandbox/how-to, and link fromevaluation.mdx. - Structural precedent: docs: add agent harness optimization concept page #1281 (agent harness optimization concept page). Also relates to docs: update glossary #1500 (glossary).
Related
- Epic: epic: built-in sandbox providers #1685 (built-in sandbox providers)
- Guide PR: [codex] Add sandbox API docs guide #1717
Activity