docs(sandbox): add Sandbox concept section

[agent-of-mkmeral]

Description

Adds a Sandbox concept section to the docs, modeled on the existing Tools and Plugins sections. It documents the sandbox feature end to end: what a sandbox is, the tools each sandbox vends, the built-in backends, driving a sandbox from your own code, how the pieces fit together, and how to build a custom one.

Why now. The sandbox abstraction (Sandbox, PosixShellSandbox, DockerSandbox, SshSandbox) and the sandbox-routed vended tools (sandbox_bash, sandbox_file_editor) shipped in both SDKs, but there was no conceptual page tying them together. A developer who sees Agent(sandbox=...) had nowhere to learn what it does, when to reach for it, or how the host fallback differs from a real isolation boundary.

Page structure

• What a sandbox is and why you would use one (the host-fallback liability)
• Configuring a Sandbox: attaching one to an agent, and the NotASandboxLocalEnvironment fallback
• Tools a Sandbox Vends: sandbox_bash / sandbox_file_editor, plus the same-name override rule
• Available Sandboxes: Docker and SSH, with their constructors and security defaults
• Working With a Sandbox Directly: execute, the file helpers, and streaming output
• How It Works: a mermaid diagram of the agent runtime vs. the sandbox boundary
• Building a Custom Sandbox: PosixShellSandbox (one method) vs. extending Sandbox, and vending tools via get_tools / getTools
• Security: the boundary is real only when the environment is isolated

Lands as a top-level Sandbox entry under Concepts in navigation.yml, between Plugins and Interventions.

Related Issues

Documents the sandbox feature shipped across the Python and TypeScript SDKs. No tracking issue in this repo.

Documentation PR

This is the documentation. New files under site/src/content/docs/user-guide/concepts/sandbox/:

• index.mdx: the page (Python inlined, TypeScript via --8<-- snippet includes)
• index.ts: runnable TypeScript snippet bodies
• index_imports.ts: matching import sets

Type of Change

Documentation update

Testing

• TypeScript snippets typecheck. Built the TypeScript SDK (strands-ts) and ran tsc --noEmit from site/test-snippets. The sandbox snippets pass; the only error is a pre-existing, unrelated pino module-resolution failure in logs.ts on main.

• Code verified against SDK source. Every API in the page was checked against strands-py/src/strands/sandbox/ and strands-ts/src/sandbox/, and Python signatures were confirmed by introspection (DockerSandbox/SshSandbox constructors, Agent(sandbox=...), get_tools() returning sandbox_file_editor + sandbox_bash, ExecutionResult/FileInfo fields).

• Full site build passes. npm run build renders the page: snippet includes resolve (no leftover --8<-- markers), the mermaid diagram and both language tabs render, and frontmatter validates against the content collection schema.

• Voice and style gate. Ran the docs-reviewer checks: no em-dashes, no emoji, no banned phrases, terminology matches the lock file, and code examples are self-contained and claim-accurate.

• I ran hatch run prepare (docs-only change; not applicable)

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[agent-of-mkmeral]

@mkmeral draft PR is up for the sandbox docs. New Sandbox concept section modeled on Tools/Plugins, covering the abstraction, the vended tools (sandbox_bash, sandbox_file_editor), the Docker and SSH backends, direct/streaming use, a runtime-vs-sandbox diagram, building a custom sandbox, and the security boundary.

Verified the works: TS snippets typecheck against the built SDK, all APIs checked against strands-py/strands-ts source, and the full npm run build renders the page cleanly. Ran it through the docs-writer self-check and docs-reviewer gate (voice, terminology, claim parity). Ready for your review on language and scope.