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 upsert / 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). |
| Create a sandbox (imperative) |
Minimum: aca sandbox create --disk ubuntu. Common knobs: --cpu 2000m, --memory 4096Mi, --env "K=V", --labels "name=dev,role=worker". Capture the printed ID into SANDBOX_ID=$(aca sandbox create --disk ubuntu -o json | jq -r .id) for reuse. For config that should live in source control, use the manifest flow (see the row below) instead. |
| Apply / deploy a sandbox manifest |
The full 3-command flow: aca sandbox init → aca sandbox validate --file sandbox.yaml → aca sandbox apply --file sandbox.yaml. Always --file (no -f short flag). State that the manifest pattern is the recommended path for CI/CD and reproducibility, in contrast to imperative aca sandbox create. If no manifest is present, run aca sandbox init — don't ask for a path. |
| Scaffold / generate a sandbox manifest |
Run (or show) aca sandbox init to scaffold a starter sandbox.yaml. Mention the commonly edited fields (disk, resources, lifecycle.autoSuspendPolicy, egressPolicy, plus ports, env, labels as needed). Mention aca sandbox schema as the way to dump the JSON Schema for editor autocomplete. |
| Run a command or open a shell in a sandbox |
Two distinct verbs: aca sandbox exec --id "$SANDBOX_ID" -c "<command>" for one-shot commands (returns stdout/stderr); aca sandbox shell --id "$SANDBOX_ID" for an interactive PTY. Anti-cue: ssh does not work — there is no SSH daemon inside the sandbox. aca sandbox exec / shell is the only path. |
| Delete a sandbox |
aca sandbox delete --id "$SANDBOX_ID" --yes. Always recommend snapshotting first if there is any state worth preserving (aca sandbox snapshot --id "$SANDBOX_ID" --name <snap>) — delete is destructive. To delete by label selector: aca sandbox list -l "name=<n>" -o json | jq -r '.[].id' | xargs -I{} aca sandbox delete --id {} --yes. |
| Read / write / copy files in a sandbox |
The aca sandbox fs family — fs write --id "$SANDBOX_ID" --path /remote/p --file ./local to upload, fs cat --id "$SANDBOX_ID" --path /remote/p to read, plus fs ls / stat / mkdir / rm [--recursive] for management. Don't suggest scp / rsync / shared filesystems — there is no SSH, and fs is the only data-plane file transport. |
| Expose a port — public preview (anonymous) |
The two-step shape: URL=$(aca sandbox port add --id "$SANDBOX_ID" --port <p> --anonymous -o json | jq -r .url), then hit $URL. State explicitly that anonymous = anyone with the URL can reach it (public preview only). Remove with aca sandbox port remove --id "$SANDBOX_ID" --port <p>. For per-user gating use the Entra row below. |
| Expose a port with Entra auth (per-user gating) |
aca sandbox port add --id "$SANDBOX_ID" --port <p> --auth entra --allow-principal <user-object-id>. Fetch the principal's object id with az ad signed-in-user show --query id -o tsv (or az ad user show --id <upn> --query id -o tsv for someone else). Pass --allow-principal once per principal you want to admit. Anti-cue: there is no --email flag — that's a stale shape; the supported gating is --auth entra + --allow-principal <object-id>. |
| Mount a shared volume |
Two-step: (1) at the group: aca sandboxgroup volume create --name <v> --type AzureBlob (multi-attach, shared) or --type DataDisk (single-attach, high-perf block). (2) at the sandbox: aca sandbox mount --id "$SANDBOX_ID" --volume <v> --path /mnt/<v>. State that the volume lives at the group level; sandboxes attach it at runtime. |
| Lock down network egress (deny-default + allow-list) |
The canonical form: aca sandbox egress set --id "$SANDBOX_ID" --default Deny --host-allow "*.github.com" --traffic-inspection Full. Multiple --host-allow "<host>" flags accumulate. Inspect current policy with aca sandbox egress show --id "$SANDBOX_ID". For production agent code, always recommend --default Deny with an explicit --host-allow list. Anti-cue: do not invent flags for individual IPs or block-lists — the only supported shape is `--default Deny |
| List / use a disk image |
The canonical "what disks are available?" verb is aca sandboxgroup disk list-public (NOT aca disks list, which does not exist). Common presets include ubuntu, debian, alpine, python, node, dotnet, and playwright. To bake your own from an OCI image: aca sandboxgroup disk create --image docker.io/library/alpine:3.19 --name <my-disk>, then aca sandbox create --disk-id <id>. Flag distinction: --disk takes the public preset name; --disk-id takes the resource ID of a private/committed disk. |
| Suspend, resume, or set auto-suspend |
Manual: aca sandbox stop --id "$SANDBOX_ID" suspends (preserves memory + disk); aca sandbox resume --id "$SANDBOX_ID" does sub-second restore. Idle policy: aca sandbox lifecycle set --id "$SANDBOX_ID" --auto-suspend <seconds> (default 300s = 5 min). State that suspended sandboxes incur storage cost only, no compute — this is the primary cost lever. |
| Snapshot / commit a sandbox |
Per-sandbox: aca sandbox snapshot --id "$SANDBOX_ID" --name <snap-name>, then boot replicas with aca sandbox create --snapshot <snap-name>. Group-level CRUD: aca sandboxgroup snapshot list / get / delete --selector "name=<snap-name>". Strongly recommend snapshotting BEFORE aca sandbox delete to preserve state. Always use --name <snap-name>, never --image (that is the wrong flag and will be rejected). Disk-only baking is aca sandbox commit --id "$SANDBOX_ID" --name <disk-name>. |
| Install the Python SDK |
The SDK is distributed as a wheel from https://aka.ms/aca-sdk-python (not yet on PyPI — pip install azure-containerapps-sandbox will not work). Canonical install: curl -L -OJ https://aka.ms/aca-sdk-python then pip install ./azure_containerapps_sandbox-*.whl (PowerShell: Invoke-WebRequest https://aka.ms/aca-sdk-python -OutFile $env:TEMP\aca-sdk.whl; pip install $env:TEMP\aca-sdk.whl). Import as from azure_containerapps_sandbox import .... The SDK and the aca CLI are interchangeable surfaces over the same data plane — pick whichever fits your runtime (CLI for shells / agents, SDK for service code). |
Compare the aca CLI vs the Azure portal |
Both surfaces exist for sandbox groups. The portal lives at https://containerapps.azure.com/sandbox-groups and is good for visual inventory, role assignments, and ad-hoc inspection. The aca CLI is the authoritative scripting / automation surface — every aca sandbox … and aca sandboxgroup … verb is available there and is what CI/CD, agents, and reproducible workflows should use. Recommend portal for discovery and one-off ops, CLI for everything programmable. |
| Compare ACA Sandboxes vs Dynamic Sessions |
Different products. ACA Sandboxes (Microsoft.App/SandboxGroups, the aca CLI) are hardware-isolated microVMs with snapshot/resume, shell/exec, port exposure, volumes, and egress policy — meant for long-running agent workloads, dev envs, MCP hosting, computer-use. Dynamic Sessions (Microsoft.App/sessionPools, the Sessions SDK) are short-lived Python/Node code-interpreter sandboxes meant for single-call LLM tool execution. If the user asks about Dynamic Sessions, redirect to those docs — do not answer with aca commands. |
| Anything in the "When NOT to use this skill" table below |
A one-paragraph redirect to the right tool or official docs. Do NOT run the out-of-scope tool's commands. Do NOT walk through options. Do NOT ask follow-up questions about the out-of-scope tool. Bow out cleanly. |
Vague / single-word prompts (sandbox, microvm, "I need a VM", "ephemeral VM for dev", "coding agent sandbox", "AI agent runtime") |
Ask one clarifying question first before jumping into aca sandbox create. Disambiguate between: (a) coding agent / dev env in a sandbox, (b) AI agent runtime, (c) MCP hosting, (d) ephemeral VM-style dev box, (e) code interpreter. Then route to the matching row above. Premature commitment to aca sandbox create on a vague prompt is a failure. |
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 --labels --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, sbx-id:/path syntax) |
| 08 |
Egress |
Deny-default outbound + host allow-list; audit decisions; YAML transforms. |
aca sandbox egress set --default Deny --host-allow "*.host.com" · egress show / decisions / apply |
| 09 |
Secrets |
Group-scoped key/value, fetched at runtime from inside the sandbox. |
aca sandboxgroup secret upsert --name X --values "K=V" · secret list / delete |
| 10 |
Managed identity |
System- or User-assigned MI on the group; grant RBAC for cross-group orchestration. |
aca sandboxgroup identity assign --system-assigned (or --user-assigned <res-id>) · identity show / remove |
| 11 |
Labels & selectors |
--labels k=v at create time; AND-filter on list. Fleet management pattern. |
aca sandbox create --labels role=worker,tenant=t42 · aca sandbox list -l role=worker |
| 12 |
Interactive shell |
Real PTY into a running sandbox. |
aca sandbox shell --id <id> |
| 13 |
YAML spec / apply |
Declarative infra-as-code: init, validate, apply, schema. |
aca sandbox init > sandbox.yaml · validate · apply --file sandbox.yaml |
| 14 |
aca doctor |
Diagnose subscription / RG / group / region / role. |
aca doctor |
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:
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.
Source: microsoft/azure-container-apps — distributed by TomeVault.
1---2name: aca-sandboxes3description: 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.4license: MIT5---67# Sandboxes89Hardware-isolated microVMs on Azure Container Apps. Snapshot/resume,10scale-to-zero, sub-second startup, deny-default egress. This skill11drives sandboxes through the **`aca` CLI** — one command surface, no12ambiguity. Self-contained — everything is under `references/` in this13folder.1415## What it is1617- **Resource type:** `Microsoft.App/SandboxGroups` (preview).18- **Isolation:** each sandbox is its own microVM, safe for untrusted code.19- **Startup:** sub-second from a prewarmed pool; suspend/resume preserves20 full memory + disk.21- **Scale:** zero to thousands; pay nothing when idle.22- **Auth:** `aca` delegates to `az login` — same identity, same MFA.2324> ⚠️ **The `az` CLI has no sandbox commands.** Sandbox groups and25> sandboxes are managed by `aca` — **not** by `az containerapp …`. The26> `az containerapp` commands are for the older Apps / Jobs surface and27> do not touch sandboxes. If you see `az containerapp sandbox …` in a28> snippet, it's wrong.2930> ⚠️ **There is no `aca sandbox-group` (hyphenated) command group.**31> Every group-level verb is `aca sandboxgroup …` (no hyphen):32> `aca sandboxgroup create / get / list / delete / role create /33> identity assign / secret upsert / disk list / volume create / snapshot …`.34> The hyphenated `--sandbox-group <name>` is the *flag* you pass to35> top-level commands to select the default group — it is not a verb.36> If you see `aca sandbox-group …` in a snippet (including for MCP37> connectors, credentials, or triggers), it's wrong / fabricated.3839## ⚠ Required cues per response type (non-negotiable)4041Before composing your answer, identify the user's intent and ensure the42cues below are present. These are **acceptance criteria, not43suggestions** — a response is incomplete if it omits any cue for its44intent.4546| User intent | Cues your response MUST include |47|---|---|48| **Install the `aca` CLI** (any OS) | (1) The curl/iwr one-liner from [references/install.md](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."** |49| **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). |50| **Create a sandbox (imperative)** | Minimum: `aca sandbox create --disk ubuntu`. Common knobs: `--cpu 2000m`, `--memory 4096Mi`, `--env "K=V"`, `--labels "name=dev,role=worker"`. Capture the printed ID into `SANDBOX_ID=$(aca sandbox create --disk ubuntu -o json \| jq -r .id)` for reuse. For config that should live in source control, use the manifest flow (see the row below) instead. |51| **Apply / deploy a sandbox manifest** | The full 3-command flow: `aca sandbox init` → `aca sandbox validate --file sandbox.yaml` → `aca sandbox apply --file sandbox.yaml`. Always `--file` (no `-f` short flag). State that **the manifest pattern is the recommended path for CI/CD and reproducibility**, in contrast to imperative `aca sandbox create`. If no manifest is present, run `aca sandbox init` — don't ask for a path. |52| **Scaffold / generate a sandbox manifest** | Run (or show) `aca sandbox init` to scaffold a starter `sandbox.yaml`. Mention the commonly edited fields (`disk`, `resources`, `lifecycle.autoSuspendPolicy`, `egressPolicy`, plus `ports`, `env`, `labels` as needed). Mention `aca sandbox schema` as the way to dump the JSON Schema for editor autocomplete. |53| **Run a command or open a shell in a sandbox** | Two distinct verbs: `aca sandbox exec --id "$SANDBOX_ID" -c "<command>"` for one-shot commands (returns stdout/stderr); `aca sandbox shell --id "$SANDBOX_ID"` for an interactive PTY. **Anti-cue:** `ssh` does not work — there is no SSH daemon inside the sandbox. `aca sandbox exec` / `shell` is the only path. |54| **Delete a sandbox** | `aca sandbox delete --id "$SANDBOX_ID" --yes`. **Always recommend snapshotting first** if there is any state worth preserving (`aca sandbox snapshot --id "$SANDBOX_ID" --name <snap>`) — delete is destructive. To delete by label selector: `aca sandbox list -l "name=<n>" -o json \| jq -r '.[].id' \| xargs -I{} aca sandbox delete --id {} --yes`. |55| **Read / write / copy files in a sandbox** | The `aca sandbox fs` family — `fs write --id "$SANDBOX_ID" --path /remote/p --file ./local` to upload, `fs cat --id "$SANDBOX_ID" --path /remote/p` to read, plus `fs ls / stat / mkdir / rm [--recursive]` for management. **Don't** suggest `scp` / `rsync` / shared filesystems — there is no SSH, and `fs` is the only data-plane file transport. |56| **Expose a port — public preview (anonymous)** | The two-step shape: `URL=$(aca sandbox port add --id "$SANDBOX_ID" --port <p> --anonymous -o json \| jq -r .url)`, then hit `$URL`. **State explicitly** that anonymous = anyone with the URL can reach it (public preview only). Remove with `aca sandbox port remove --id "$SANDBOX_ID" --port <p>`. For per-user gating use the Entra row below. |57| **Expose a port with Entra auth (per-user gating)** | `aca sandbox port add --id "$SANDBOX_ID" --port <p> --auth entra --allow-principal <user-object-id>`. Fetch the principal's object id with `az ad signed-in-user show --query id -o tsv` (or `az ad user show --id <upn> --query id -o tsv` for someone else). Pass `--allow-principal` once per principal you want to admit. **Anti-cue:** there is **no `--email` flag** — that's a stale shape; the supported gating is `--auth entra` + `--allow-principal <object-id>`. |58| **Mount a shared volume** | Two-step: (1) at the group: `aca sandboxgroup volume create --name <v> --type AzureBlob` (multi-attach, shared) or `--type DataDisk` (single-attach, high-perf block). (2) at the sandbox: `aca sandbox mount --id "$SANDBOX_ID" --volume <v> --path /mnt/<v>`. State that **the volume lives at the group level**; sandboxes attach it at runtime. |59| **Lock down network egress (deny-default + allow-list)** | The canonical form: `aca sandbox egress set --id "$SANDBOX_ID" --default Deny --host-allow "*.github.com" --traffic-inspection Full`. Multiple `--host-allow "<host>"` flags accumulate. Inspect current policy with `aca sandbox egress show --id "$SANDBOX_ID"`. For production agent code, **always recommend `--default Deny`** with an explicit `--host-allow` list. **Anti-cue:** do not invent flags for individual IPs or block-lists — the only supported shape is `--default Deny|Allow` plus repeated `--host-allow`. |60| **List / use a disk image** | The canonical "what disks are available?" verb is **`aca sandboxgroup disk list-public`** (NOT `aca disks list`, which does not exist). Common presets include `ubuntu`, `debian`, `alpine`, `python`, `node`, `dotnet`, and `playwright`. To bake your own from an OCI image: `aca sandboxgroup disk create --image docker.io/library/alpine:3.19 --name <my-disk>`, then `aca sandbox create --disk-id <id>`. **Flag distinction:** `--disk` takes the public preset name; `--disk-id` takes the resource ID of a private/committed disk. |61| **Suspend, resume, or set auto-suspend** | Manual: `aca sandbox stop --id "$SANDBOX_ID"` suspends (preserves memory + disk); `aca sandbox resume --id "$SANDBOX_ID"` does sub-second restore. Idle policy: `aca sandbox lifecycle set --id "$SANDBOX_ID" --auto-suspend <seconds>` (default 300s = 5 min). State that **suspended sandboxes incur storage cost only, no compute** — this is the primary cost lever. |62| **Snapshot / commit a sandbox** | Per-sandbox: `aca sandbox snapshot --id "$SANDBOX_ID" --name <snap-name>`, then boot replicas with `aca sandbox create --snapshot <snap-name>`. Group-level CRUD: `aca sandboxgroup snapshot list / get / delete --selector "name=<snap-name>"`. **Strongly recommend snapshotting BEFORE `aca sandbox delete`** to preserve state. Always use `--name <snap-name>`, **never `--image`** (that is the wrong flag and will be rejected). Disk-only baking is `aca sandbox commit --id "$SANDBOX_ID" --name <disk-name>`. |63| **Install the Python SDK** | The SDK is distributed as a wheel from `https://aka.ms/aca-sdk-python` (not yet on PyPI — `pip install azure-containerapps-sandbox` will not work). Canonical install: `curl -L -OJ https://aka.ms/aca-sdk-python` then `pip install ./azure_containerapps_sandbox-*.whl` (PowerShell: `Invoke-WebRequest https://aka.ms/aca-sdk-python -OutFile $env:TEMP\aca-sdk.whl; pip install $env:TEMP\aca-sdk.whl`). Import as `from azure_containerapps_sandbox import ...`. The SDK and the `aca` CLI are interchangeable surfaces over the same data plane — pick whichever fits your runtime (CLI for shells / agents, SDK for service code). |64| **Compare the `aca` CLI vs the Azure portal** | Both surfaces exist for sandbox groups. The portal lives at **`https://containerapps.azure.com/sandbox-groups`** and is good for visual inventory, role assignments, and ad-hoc inspection. The `aca` CLI is the authoritative scripting / automation surface — every `aca sandbox …` and `aca sandboxgroup …` verb is available there and is what CI/CD, agents, and reproducible workflows should use. Recommend **portal for discovery and one-off ops, CLI for everything programmable**. |65| **Compare ACA Sandboxes vs Dynamic Sessions** | **Different products.** ACA Sandboxes (`Microsoft.App/SandboxGroups`, the `aca` CLI) are hardware-isolated microVMs with snapshot/resume, shell/exec, port exposure, volumes, and egress policy — meant for long-running agent workloads, dev envs, MCP hosting, computer-use. Dynamic Sessions (`Microsoft.App/sessionPools`, the Sessions SDK) are short-lived Python/Node code-interpreter sandboxes meant for single-call LLM tool execution. If the user asks about Dynamic Sessions, redirect to those docs — do **not** answer with `aca` commands. |66| **Anything in the "When NOT to use this skill" table below** | A one-paragraph redirect to the right tool or official docs. **Do NOT** run the out-of-scope tool's commands. **Do NOT** walk through options. **Do NOT** ask follow-up questions about the out-of-scope tool. Bow out cleanly. |67| **Vague / single-word prompts** (`sandbox`, `microvm`, "I need a VM", "ephemeral VM for dev", "coding agent sandbox", "AI agent runtime") | **Ask one clarifying question first** before jumping into `aca sandbox create`. Disambiguate between: (a) coding agent / dev env in a sandbox, (b) AI agent runtime, (c) MCP hosting, (d) ephemeral VM-style dev box, (e) code interpreter. Then route to the matching row above. Premature commitment to `aca sandbox create` on a vague prompt is a failure. |6869## When **NOT** to use this skill (hard reject + redirect)7071If the user's task is **not about ACA Sandboxes**, refuse and redirect72in one short reply — don't run any commands, don't walk through options,73don't ask clarifying questions about the out-of-scope tool. The skill74activated by mistake; bow out cleanly.7576| User asks about… | Reply pattern |77|---|---|78| `azd init`, `azd up`, `azd deploy`, project scaffolding | "That's the Azure Developer CLI (`azd`), not ACA Sandboxes. See the [azd docs](https://learn.microsoft.com/azure/developer/azure-developer-cli/). Sandboxes don't have an `init`/`up`/`deploy` command and aren't a project bootstrapper." |79| `az acr build`, `docker build`, registry pushes | "That's Azure Container Registry / Docker, not ACA Sandboxes. See the [`az acr` docs](https://learn.microsoft.com/cli/azure/acr). Sandboxes consume disk images, not container images." |80| 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." |81| 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." |82| 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." |8384**Never** start running the out-of-scope tool's commands "just to help." A one-paragraph redirect is the correct, complete answer.8586## Get started8788| | Where |89|---|---|90| **Install** | [references/install.md](references/install.md) |91| **Prerequisites** | [references/prerequisites.md](references/prerequisites.md) |92| **Quick start** | [references/quickstart.md](references/quickstart.md) |93| **Full CLI reference** | [references/reference.md](references/reference.md) |94| **Scenario recipes** | [references/scenarios.md](references/scenarios.md) |9596After install, always confirm setup with `aca doctor` — it resolves97subscription / RG / group / region / role and tells you which check98is red.99100## Try asking101102Once the skill is loaded, paste any of these into your agent. Each one103exercises a different capability — together they show the canonical104shape for the most common sandbox tasks (and they double as a routing105smoke test if you're testing changes to this skill).106107| Try saying | What you should get back |108|---|---|109| *"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` |110| *"set up a sandbox group from scratch"* | the full 4-step bootstrap (group create + Data Owner role + `aca doctor` gate) |111| *"create an ubuntu sandbox and run uname -a in it"* | `aca sandbox create` with ID capture, then `aca sandbox exec` |112| *"how do I ssh into my sandbox?"* | corrective answer — no SSH daemon; use `aca sandbox shell` or `exec` |113| *"copy data.csv into my sandbox"* | `aca sandbox fs write --path … --file …` (and the anti-`scp` note) |114| *"expose port 8080 publicly"* | `aca sandbox port add --anonymous -o json \| jq -r .url` |115| *"mount a shared volume on two sandboxes"* | `aca sandboxgroup volume create --type AzureBlob` + `aca sandbox mount` |116| *"restrict outbound traffic to github.com only"* | `aca sandbox egress set --default Deny --rule "*.github.com:Allow"` |117| *"snapshot my sandbox before I tear it down"* | `aca sandbox snapshot --name <s>` followed by `aca sandbox delete --yes` |118| *"suspend my sandbox to save money"* | `aca sandbox stop`/`resume` plus `aca sandbox lifecycle set --auto-suspend` |119| *"give me a YAML manifest for a 2 vCPU sandbox"* | `aca sandbox init` → edit → `aca sandbox validate --file` → `aca sandbox apply --file` |120121## Capabilities122123Everything the platform exposes. Each row is the starting point — open124[references/reference.md](references/reference.md) for full flags and125options.126127> Command rows below show only the **shape**. In real invocations:128> - every `aca sandbox <verb>` takes `--id <sandbox-id>`;129> - every `aca sandboxgroup <noun> <verb>` mutation takes `--name <group>`130> (or relies on the default group set via `--set-config`);131> - omit these from copies into the shell and you'll get a CLI parse error.132133| # | Capability | What it does | `aca` CLI |134|----|---------------------------|------------------------------------------------------------------------------|-----------|135| 00 | **Sandbox groups** | Provision, list/get, assign Data Owner role, tear down. | `aca sandboxgroup create / list / get / role create / delete` |136| 01 | **Sandboxes** | Create, list, get, delete; cpu/memory/labels/env; parallel. | `aca sandbox create / list / get / delete` (+ `--cpu --memory --labels --env`) |137| 02 | **Snapshots** | Freeze a running sandbox; boot new ones from that point. | `aca sandbox snapshot --id <id> --name X` · `aca sandbox create --snapshot X` |138| 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) |139| 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` |140| 05 | **Lifecycle** | Stop/resume; auto-suspend after idle; auto-delete after TTL. | `aca sandbox stop / resume` · `aca sandbox lifecycle set --auto-suspend 60` |141| 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` |142| 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, `sbx-id:/path` syntax) |143| 08 | **Egress** | Deny-default outbound + host allow-list; audit decisions; YAML transforms. | `aca sandbox egress set --default Deny --host-allow "*.host.com"` · `egress show / decisions / apply` |144| 09 | **Secrets** | Group-scoped key/value, fetched at runtime from inside the sandbox. | `aca sandboxgroup secret upsert --name X --values "K=V"` · `secret list / delete` |145| 10 | **Managed identity** | System- or User-assigned MI on the group; grant RBAC for cross-group orchestration. | `aca sandboxgroup identity assign --system-assigned` (or `--user-assigned <res-id>`) · `identity show / remove` |146| 11 | **Labels & selectors** | `--labels k=v` at create time; AND-filter on list. Fleet management pattern. | `aca sandbox create --labels role=worker,tenant=t42` · `aca sandbox list -l role=worker` |147| 12 | **Interactive shell** | Real PTY into a running sandbox. | `aca sandbox shell --id <id>` |148| 13 | **YAML spec / `apply`** | Declarative infra-as-code: `init`, `validate`, `apply`, `schema`. | `aca sandbox init > sandbox.yaml` · `validate` · `apply --file sandbox.yaml` |149| 14 | **`aca doctor`** | Diagnose subscription / RG / group / region / role. | `aca doctor` |150151## Scenarios152153Composed patterns that combine the capabilities above. Full sketches154in [references/scenarios.md](references/scenarios.md).155156- **Web apps** — start a server, expose a port anonymously, hit the URL.157- **Coding agents in a sandbox** — run Copilot CLI / Claude Code / Codex158 with deny-default egress and (optionally) token-swap rules.159- **Code interpreter** — LLM generates → exec → observe → iterate;160 snapshot between turns for rewind.161- **Swarms** — orchestrator fans work across N worker sandboxes by162 label selector.163- **Sandbox inception** — orchestrator runs *inside* a sandbox and uses164 its managed identity to drive a separate worker group. No credentials165 in agent code.166- **Computer-use** — LLM drives a real browser; watch live via noVNC.167- **MCP hosting** — host an MCP server in a sandbox; expose via port or168 Dev Tunnel.169- **Data processing** — producer/consumer pipelines on shared170 `AzureBlob` volumes.171- **Developer workflows** — PR builds, ephemeral CI, on-demand dev envs.172173## Python SDK — install + use174175The Python SDK ([`azure-containerapps-sandbox`](https://pypi.org/project/azure-containerapps-sandbox/)) is the programmatic counterpart to the `aca` CLI and is in public preview. Install from PyPI:176177```bash178pip install azure-containerapps-sandbox179```180181Import as:182183```python184from azure_containerapps_sandbox import SandboxGroupsClient185```186187The SDK and the `aca` CLI are interchangeable surfaces over the same188control plane — pick whichever fits your runtime (CLI for shells /189agents / scripts, SDK for service code). When in doubt or for190agent-driven self-installs, prefer the CLI install path above.191192---193> Source: [microsoft/azure-container-apps](https://github.com/microsoft/azure-container-apps) — distributed by [TomeVault](https://tomevault.io).194<!-- tomevault:4.0:skill_md:2026-06-18 -->
tomevault-io