diff --git a/plugin/skills/sandboxes/SKILL.md b/plugin/skills/sandboxes/SKILL.md index 8e1f9d3..2823ce6 100644 --- a/plugin/skills/sandboxes/SKILL.md +++ b/plugin/skills/sandboxes/SKILL.md @@ -1,26 +1,56 @@ --- name: sandboxes description: | - Azure Container Apps sandboxes let you run untrusted code, agents, - MCP servers, and web apps in hardware-isolated microVMs. - Supports snapshot/resume, scale-to-zero, deny-default egress, and is - managed with `aca` CLI using `az login`. + Azure Container Apps Sandboxes (ACA Sandboxes) let a developer run + untrusted code, agents, MCP servers, and web apps in their OWN + hardware-isolated microVM. Long-lived (hours-to-days), developer-owned, + programmatically controlled via the `aca` CLI (which uses + `aca auth login`, delegating to `az login` under the hood). Use when the user wants to: create/manage sandbox groups and sandboxes; exec or open a shell; read/write files; expose ports; snapshot, stop, resume, commit to disk; mount volumes; tighten egress; manage secrets, identity, labels; apply YAML; or run - scenarios like web apps, coding agents, code interpreter, swarms, + scenarios like web apps, coding agents, agent swarms, computer-use, or MCP hosting. + **Do NOT activate for:** + - **Container Apps Dynamic Sessions** (the LLM "code interpreter" + product — ephemeral seconds-long sessions, Hyper-V isolation, used + for executing untrusted code GENERATED BY an LLM tool/agent at + runtime). Different product in the same family. If the user mentions + "code interpreter", "execute LLM-generated code", "untrusted code + from my agent", "session pool", "ephemeral seconds", point them at + Container Apps Dynamic Sessions instead. + - Kubernetes / AKS "sandbox" namespaces or pods. + - Cosmos DB "sandbox" containers / databases. + - Windows Sandbox, Linux namespace sandboxes, Salesforce Sandbox, + Playwright sandbox, browser sandboxes. + - Generic "VM in Azure" without ACA / microVM / dev-loop context + (could be Azure VM, Dev Box, Codespaces). + + **When the prompt is ambiguous, ASK ONE clarifying question before + provisioning anything.** Specifically: + - Single-word prompts ("sandbox", "microVM", "VM") — ask which product + family (ACA Sandboxes, Dynamic Sessions, Azure VM, Dev Box, …). + - "Ephemeral VM" / "I need a VM for testing" — ask expected lifetime + (seconds → Dynamic Sessions; hours-to-days → ACA Sandboxes; long-lived + workstation → Dev Box / Azure VM). + - "Set up a sandbox for my coding agent" / "What should I use to run + my AI agent?" — ask whether (a) the agent needs its OWN dev + environment (ACA Sandboxes is the strong fit) or (b) the agent needs + to execute end-user / LLM-generated code (Dynamic Sessions). + If `aca` is missing, read `references/install.md` first. `aca` ships ONLY via GitHub Releases (microsoft/azure-container-apps); not npm/pip/winget/brew. Don't guess. - Triggers: install aca, install aca cli, setup aca, aca doctor, aca - login, command not found: aca, create sandbox, sandbox group, aca - cli, aca sandbox, exec in sandbox, microVM, code interpreter, agent - swarm, host mcp. + Triggers (must have ACA / microVM / dev-loop context — bare keywords + alone are NOT enough; ask first per above): install aca, install aca + cli, setup aca, aca doctor, aca auth login, aca login, command not + found: aca, create ACA sandbox, sandbox group, aca cli, aca sandbox, + exec in ACA sandbox, ACA microVM, host mcp in sandbox, personal agent + sandbox. --- # Sandboxes @@ -38,7 +68,8 @@ folder. - **Startup:** sub-second from a prewarmed pool; suspend/resume preserves full memory + disk. - **Scale:** zero to thousands; pay nothing when idle. -- **Auth:** `aca` delegates to `az login` — same identity, same MFA. +- **Auth:** `aca auth login` — delegates to `az login` under the hood, + same identity, same MFA. > ⚠️ **The `az` CLI has no sandbox commands.** Sandbox groups and > sandboxes are managed by `aca` — **not** by `az containerapp …`. The @@ -46,6 +77,21 @@ folder. > do not touch sandboxes. If you see `az containerapp sandbox …` in a > snippet, it's wrong. +## ACA Sandboxes vs. adjacent products (don't confuse them) + +| | **ACA Sandboxes** | **Container Apps Dynamic Sessions** | **Regular Container App** | +|---|---|---|---| +| Audience | Developer / agent owner | LLM tool runtime | Production HTTP service | +| Lifetime | Hours → days, snapshot/resume | Seconds → minutes, ephemeral | Indefinite, auto-scale 0→N | +| Isolation | microVM (hardware) | Hyper-V (hardware, per-session) | Shared container runtime | +| Managed via | `aca` CLI, YAML manifests | Dynamic Sessions API / SDK | `az containerapp`, Bicep | +| Use it for | Personal dev env, MCP host, agent dev loop, swarms | LLM-generated untrusted code, code interpreter as a service | Web apps, APIs, jobs | +| Portal | `https://containerapps.azure.com/sandbox-groups` | Azure portal `Microsoft.App/sessionPools` | Azure portal `Microsoft.App/containerApps` | + +If the user's intent matches the middle column, **stop and point them +at Container Apps Dynamic Sessions** — don't try to make ACA Sandboxes +fit. + ## Get started | | Where | @@ -55,6 +101,7 @@ folder. | **Quick start** | [references/quickstart.md](references/quickstart.md) | | **Full CLI reference** | [references/reference.md](references/reference.md) | | **Scenario recipes** | [references/scenarios.md](references/scenarios.md) | +| **Portal** | [`https://containerapps.azure.com/sandbox-groups`](https://containerapps.azure.com/sandbox-groups) — exploration, visual inspection of groups/sandboxes/ports/logs. The CLI is primary; the portal complements it for one-off ops. | After install, always confirm setup with `aca doctor` — it resolves subscription / RG / group / region / role and tells you which check @@ -98,8 +145,10 @@ in [references/scenarios.md](references/scenarios.md). - **Web apps** — start a server, expose a port anonymously, hit the URL. - **Coding agents in a sandbox** — run Copilot CLI / Claude Code / Codex with deny-default egress and (optionally) token-swap rules. -- **Code interpreter** — LLM generates → exec → observe → iterate; - snapshot between turns for rewind. +- **Developer code-interpreter loop** — your OWN agent generates code, + execs it inside YOUR sandbox, snapshots between turns for rewind. + For LLM tools / managed code-interpreter-as-a-service used by end-user + agents at runtime, use **Container Apps Dynamic Sessions** instead. - **Swarms** — orchestrator fans work across N worker sandboxes by label selector. - **Sandbox inception** — orchestrator runs *inside* a sandbox and uses