aca-sandboxes

name	aca-sandboxes
description	Use when the user wants to create, manage, or operate Azure Container Apps sandboxes — hardware-isolated microVMs driven by the `aca` CLI. USE FOR: create sandbox group, create sandbox, aca doctor, aca auth login, install aca, exec in sandbox, sandbox shell, fs read/write, expose port, mount volume, snapshot/suspend/resume sandbox, commit to disk, egress rules, secrets, identity, list disk images, Python SDK install, Azure portal sandbox surface, compare to Dynamic Sessions or Container Apps, scenarios like coding agents, code interpreter, agent swarms, computer-use, web apps, MCP hosting. DO NOT USE FOR: regular Azure Container Apps (`Microsoft.App/containerApps`), AKS, or VM workloads.
license	MIT
metadata	{"author":"Microsoft","version":"0.0.5-beta"}

Sandboxes

Hardware-isolated microVMs on Azure Container Apps. Snapshot/resume, scale-to-zero, sub-second startup, deny-default egress. This skill drives sandboxes through the aca CLI — one command surface, no ambiguity. Self-contained — everything is under references/ in this folder.

What it is

• Resource type: Microsoft.App/SandboxGroups (preview).
• Isolation: each sandbox is its own microVM, safe for untrusted code.
• 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.

⚠️ The az CLI has no sandbox commands. Sandbox groups and sandboxes are managed by aca — not by az containerapp …. The az containerapp commands are for the older Apps / Jobs surface and do not touch sandboxes. If you see az containerapp sandbox … in a snippet, it's wrong.

⚠️ There is no aca sandbox-group (hyphenated) command group. Every group-level verb is aca sandboxgroup … (no hyphen): aca sandboxgroup create / get / list / delete / role create / identity assign / secret set / disk list / volume create / snapshot …. The hyphenated --sandbox-group <name> is the flag you pass to top-level commands to select the default group — it is not a verb. If you see aca sandbox-group … in a snippet (including for MCP connectors, credentials, or triggers), it's wrong / fabricated.

⚠ Required cues per response type (non-negotiable)

Before composing your answer, identify the user's intent and ensure the cues below are present. These are acceptance criteria, not suggestions — a response is incomplete if it omits any cue for its intent.

User intent	Cues your response MUST include
Install the aca CLI (any OS)	(1) The curl/iwr one-liner from references/install.md — use the https://aka.ms/aca-cli-install (Linux/macOS) and https://aka.ms/aca-cli-install-ps (Windows) short URLs. (2) aca --version + auth-aware sign-in (az account show -o none 2>$null; if ($LASTEXITCODE -ne 0) { az login }, then aca auth login to acquire an aca token — never call az login or aca auth login unconditionally; gate both on a status check) + aca doctor. The CLI surface for auth is aca auth login (the top-level aca binary does not have a bare login subcommand). (3) The explicit sentence: "this same install path is also used inside sandboxes and containers for agent-driven self-installs."
Bootstrap a sandbox group (one-time setup)	The 4-step flow: check auth first (az account show -o none 2>$null; if ($LASTEXITCODE -ne 0) { az login }, then aca auth login if aca is not yet authenticated — never call az login or aca auth login unconditionally) → aca sandboxgroup create --name <g> --location <region> --set-config → aca sandboxgroup role create --role "Container Apps SandboxGroup Data Owner" --principal-id $(az ad signed-in-user show --query id -o tsv) → aca doctor. --set-config is required so subsequent aca sandbox … commands don't need --group on every call. Treat green aca doctor as the gate before doing anything else. Heads-up: aca sandboxgroup create already grants the Data Owner role to the calling principal, so the explicit role create is only needed when granting access to additional principals (use --skip-role-check on create if you want to defer).

When NOT to use this skill (hard reject + redirect)

If the user's task is not about ACA Sandboxes, refuse and redirect in one short reply — don't run any commands, don't walk through options, don't ask clarifying questions about the out-of-scope tool. The skill activated by mistake; bow out cleanly.

User asks about…	Reply pattern
azd init, azd up, azd deploy, project scaffolding	"That's the Azure Developer CLI (azd), not ACA Sandboxes. See the azd docs. Sandboxes don't have an init/up/deploy command and aren't a project bootstrapper."
az acr build, docker build, registry pushes	"That's Azure Container Registry / Docker, not ACA Sandboxes. See the az acr docs. Sandboxes consume disk images, not container images."
Cosmos / SQL / data-plane queries to other Azure services	"That's the relevant data service (Cosmos DB, Azure SQL, etc.), not ACA Sandboxes. Use that service's CLI / SDK / portal."
Listing Kubernetes pods, AKS cluster ops, kubectl	"That's AKS / Kubernetes, not ACA Sandboxes. Use kubectl or the AKS docs. Sandboxes are individual microVMs, not a Kubernetes cluster."
Deploying a Function App, App Service site, full Container App (Apps/Jobs)	"That's Azure Functions / App Service / Container Apps (apps and jobs), not Sandboxes. Use those products' deployment docs."

Never start running the out-of-scope tool's commands "just to help." A one-paragraph redirect is the correct, complete answer.

Get started

	Where
Install	references/install.md
Prerequisites	references/prerequisites.md
Quick start	references/quickstart.md
Full CLI reference	references/reference.md
Scenario recipes	references/scenarios.md

After install, always confirm setup with aca doctor — it resolves subscription / RG / group / region / role and tells you which check is red.

Try asking

Once the skill is loaded, paste any of these into your agent. Each one exercises a different capability — together they show the canonical shape for the most common sandbox tasks (and they double as a routing smoke test if you're testing changes to this skill).

Try saying	What you should get back
"install the aca cli"	the aka.ms/aca-cli-install one-liner + aca --version + auth-aware az account show; az login *only* if it fails + aca doctor
"set up a sandbox group from scratch"	the full 4-step bootstrap (group create + Data Owner role + aca doctor gate)
"create an ubuntu sandbox and run uname -a in it"	aca sandbox create with ID capture, then aca sandbox exec
"how do I ssh into my sandbox?"	corrective answer — no SSH daemon; use aca sandbox shell or exec
"copy data.csv into my sandbox"	aca sandbox fs write --path … --file … (and the anti-scp note)
"expose port 8080 publicly"	aca sandbox port add --anonymous -o json | jq -r .url
"mount a shared volume on two sandboxes"	aca sandboxgroup volume create --type AzureBlob + aca sandbox mount
"restrict outbound traffic to github.com only"	aca sandbox egress set --default Deny --rule "*.github.com:Allow"
"snapshot my sandbox before I tear it down"	aca sandbox snapshot --name <s> followed by aca sandbox delete --yes
"suspend my sandbox to save money"	aca sandbox stop/resume plus aca sandbox lifecycle set --auto-suspend
"give me a YAML manifest for a 2 vCPU sandbox"	aca sandbox init → edit → aca sandbox validate --file → aca sandbox apply --file

Capabilities

Everything the platform exposes. Each row is the starting point — open references/reference.md for full flags and options.

Command rows below show only the shape. In real invocations:

• every aca sandbox <verb> takes --id <sandbox-id>;
• every aca sandboxgroup <noun> <verb> mutation takes --name <group> (or relies on the default group set via --set-config);
• omit these from copies into the shell and you'll get a CLI parse error.

#	Capability	What it does	aca CLI
00	Sandbox groups	Provision, list/get, assign Data Owner role, tear down.	aca sandboxgroup create / list / get / role create / delete
01	Sandboxes	Create, list, get, delete; cpu/memory/labels/env; parallel.	aca sandbox create / list / get / delete (+ --cpu --memory --label --env)
02	Snapshots	Freeze a running sandbox; boot new ones from that point.	aca sandbox snapshot --id <id> --name X · aca sandbox create --snapshot X
03	Disks	Public disks, build from container image, commit a running sandbox.	aca sandboxgroup disk list-public / create --image · aca sandbox commit --id <id> --name X · aca sandbox create --disk <public-name> (or --disk-id <id> for private/committed disks)
04	Volumes	AzureBlob (shared) or DataDisk (block); mount at create or post-create.	aca sandboxgroup volume create --type AzureBlob · aca sandbox mount --volume X --path /mnt/x
05	Lifecycle	Stop/resume; auto-suspend after idle; auto-delete after TTL.	aca sandbox stop / resume · aca sandbox lifecycle set --auto-suspend 60
06	Ports	Expose an HTTP port; anonymous or Entra-gated (--auth entra --allow-principal); revoke.	aca sandbox port add --port 8080 [--anonymous | --auth entra --allow-principal <object-id>] · port list / remove
07	Files	write / read / list / stat / mkdir / delete inside the sandbox.	aca sandbox fs write --file ./local · fs cat / ls · fs cp <src> <dst> (positional, syntax)

Scenarios

Composed patterns that combine the capabilities above. Full sketches in 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.
• Swarms — orchestrator fans work across N worker sandboxes by label selector.
• Sandbox inception — orchestrator runs inside a sandbox and uses its managed identity to drive a separate worker group. No credentials in agent code.
• Computer-use — LLM drives a real browser; watch live via noVNC.
• MCP hosting — host an MCP server in a sandbox; expose via port or Dev Tunnel.
• Data processing — producer/consumer pipelines on shared AzureBlob volumes.
• Developer workflows — PR builds, ephemeral CI, on-demand dev envs.

Python SDK — install + use

The Python SDK (azure-containerapps-sandbox) is the programmatic counterpart to the aca CLI and is in public preview. Install from PyPI (preflight uv first — install the upstream installer if it's missing):

# Linux / macOS
command -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install azure-containerapps-sandbox

# Windows
if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
  irm https://astral.sh/uv/install.ps1 | iex
}
uv pip install azure-containerapps-sandbox

Import as:

from azure_containerapps_sandbox import SandboxGroupsClient

The SDK and the aca CLI are interchangeable surfaces over the same control plane — pick whichever fits your runtime (CLI for shells / agents / scripts, SDK for service code). When in doubt or for agent-driven self-installs, prefer the CLI install path above.