docs: aspirational — Squad tools in ACA Dynamic Sessions and Sandboxes (preview platform features) #1569

⚠️ Aspirational / Preview

This issue documents a future docs deliverable gated on Azure platform stability. Both Azure Container Apps Dynamic Sessions (custom containers) and ACA Sandboxes (Microsoft.App/SandboxGroups) involve features that are in preview or recently GA at the time of filing. Docs delivery is explicitly blocked on verified stable platform support. Do not merge these pages until the platform status is confirmed and the integration patterns are tested against a stable API.

Parent issue: #1564

Problem

Tamir Dresher has published two detailed posts on using ACA Dynamic Sessions (ephemeral tool execution sandboxing) and ACA Sandboxes (persistent workspaces, preview) with Squad. Both represent the correct long-term execution safety model for Squad tools — isolating agentic tool execution so a compromised or runaway tool cannot affect the Squad control plane. However, the platform features are not stable enough to publish as supported Squad guidance today.

What These Features Enable

• ACA Dynamic Sessions (custom containers, GA for custom containers): Ephemeral, isolated containers spun up per tool invocation. Squad dispatches tool calls to a session worker via HTTP. The session is destroyed after use. No persistent state in the execution environment.
• ACA Sandboxes (preview, Microsoft.App/SandboxGroups): Persistent, isolated workspace containers with separate disk images. Appropriate for multi-turn tool environments where state must survive across Squad sessions. Disk image is separated from credentials.

Scope

Two scenario pages, both carrying Aspirational / Preview banners:

Page A: docs/src/content/docs/scenarios/tool-sandboxing-aca.md

• Why tool isolation matters: blast radius, credential scope, runaway tool protection
• Dynamic Sessions vs ACA Sandboxes: comparison table (ephemeral/bounded vs persistent/multi-turn)
• Architecture pattern: control plane (Squad/LangGraph) / tool plane (ACA session) split
• HTTP worker contract design for the session-plane worker
• Security checklist: no open shell, narrow HTTP API, egress rules, ephemeral = no persistent state
• Prerequisites: preview subscription, aca CLI, custom container image
• Cross-link to docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566 (ACA hosting guide — prerequisite reading)

Page B: docs/src/content/docs/scenarios/persistent-workspace-aca-sandboxes.md

• When to use ACA Sandboxes vs Dynamic Sessions
• Control plane vs workspace separation principle: Squad state stays in app/repo, not sandbox
• Sandbox-group credential setup for GitHub Copilot provider token
• aca CLI setup (note: separate from az containerapp)
• Disk image separation from credentials
• Egress rule configuration

Acceptance Criteria

• Both pages carry explicit Aspirational/Preview banners
• Dynamic Sessions vs Sandboxes distinction is clear (ephemeral vs persistent)
• Security checklists present on both pages
• No acceptance criterion requires current ACA preview features to be stable — pages acknowledge instability and expected breaking changes
• Platform status (ACA Dynamic Sessions GA for custom containers; ACA Sandboxes preview) is re-verified before merge
• Cross-links to docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566 (ACA hosting guide) since that is prerequisite context

Non-Goals

• Shipping docs before the platform API is stable
• Claiming ACA Sandboxes are GA (they are not at filing time)
• Covering Squad core hosting on ACA (that is docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566)

Source / Inspiration

Tamir Dresher published two posts on this topic. These are inspiration and citation sources — content must be written in Squad voice, not copied. Tamir's clarification of the Dynamic Sessions vs Sandboxes distinction is the primary reference for the comparison table.

Relation to Existing Issues

• docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566 — Dependency. ACA Dynamic Sessions is the sandboxing layer on top of ACA hosting. docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566 must ship first so readers have the hosting context.
• docs milestone: real-world Squad hosting, integrations, and operations #1564 — Parent umbrella.

Priority / Gate

P2 — Aspirational. File now. Gate merge on: (1) CHILD-2 (#1566) merged, (2) ACA Sandboxes preview stabilizes with documented Squad integration pattern, (3) content reviewed by Tamir or Azure team liaison.