Skip to content

docs: add Concepts page for sandboxes (runtime vs sandbox vs provider) #1723

Description

@cwing-nvidia

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

Implementation notes

  • Move/condense the runtime-vs-sandbox definition out of about/concepts/environments.mdx into 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 from evaluation.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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions