Skip to content

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

Open

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions