@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-repo/skills/aca-sandboxes/references/reference.md

@@ -0,0 +1,287 @@
+# `aca` CLI reference
+
+Full reference for the `aca` CLI, part 1 of 2: auth, help, global flags, environment variables, config, and `doctor`. See [reference-advanced.md](reference-advanced.md) for the YAML spec workflow, selectors, output formats, and verbose/debug.
+
+> Verified against `aca 1.0.0-beta.1`.
+
+## Contents
+
+- [Auth](#auth)
+- [Help commands](#help-commands)
+- [Global flags and short forms](#global-flags-and-short-forms)
+- [Environment variables](#environment-variables)
+- [Config](#config)
+- [`doctor`](#doctor)
+
+---
+
+---
+
+## Auth
+
+`aca` does not maintain its own credential store. Auth is delegated to
+the Azure CLI — same identity, same MFA, same conditional-access policies.
+
+```bash
+aca auth login    # delegates to `az login`
+aca auth status   # shows current ARM + data-plane auth
+```
+
+`aca auth status` output:
+
+```
+✓ ARM authenticated via Azure CLI
+✓ Data plane authenticated (https://dynamicsessions.io/.default)
+```
+
+### Switching subscriptions
+
+`aca` reads the active Azure CLI account by default. Switch it with `az`:
+
+```bash
+az account set --subscription <SUB_ID>
+```
+
+Or override per-command:
+
+```bash
+aca sandbox list -s <SUB_ID>
+```
+
+Or set a default in CLI config:
+
+```bash
+aca config set -s <SUB_ID>
+```
+
+### Managed identity (Azure-hosted)
+
+When running inside Azure (App Service, Container Apps, VM, Functions),
+use a managed identity:
+
+```bash
+aca sandbox list --managed-identity system            # system-assigned
+aca sandbox list --managed-identity <CLIENT_ID_UUID>  # user-assigned
+```
+
+Available on every command. Also settable via
+`ACA_SANDBOX_MANAGED_IDENTITY` or
+`aca config sandbox set --managed-identity …`.
+
+---
+
+## Help commands
+
+Every command, group, and sub-group responds to `--help` (or `-h`). The
+help text is the source of truth — examples, flags, env-var names, and
+defaults are all there.
+
+```bash
+aca --help                          # top-level: commands + global flags + quick start + scenarios
+aca <group> --help                  # group: list of sub-commands
+aca <group> <command> --help        # command: arguments, env vars, defaults, examples
+aca <group> <command> -h            # short summary
+```
+
+Top-level commands:
+
+| Command | Purpose |
+|---|---|
+| `aca auth`         | Log in and check authentication status |
+| `aca config`       | Manage CLI configuration |
+| `aca sandboxgroup` | Manage sandbox groups, disks, volumes, secrets, roles, regions |
+| `aca sandbox`      | Create and manage sandboxes (exec, shell, files, ports, egress, snapshots) |
+| `aca version`      | Show CLI version |
+| `aca doctor`       | Check prerequisites, config, and RBAC (8 checks) |
+| `aca help`         | Print help for any sub-command |
+
+---
+
+## Global flags and short forms
+
+Every command accepts these flags. Short forms are listed where they exist.
+
+| Flag | Short | Env var | Description |
+|---|---|---|---|
+| `--subscription`      | `-s` | `ACA_SUBSCRIPTION`               | Azure subscription ID |
+| `--resource-group`    | `-g` | `ACA_RESOURCE_GROUP`             | Resource group |
+| `--sandbox-group`     |      | `ACA_SANDBOX_GROUP`              | Default sandbox group (top-level commands) |
+| `--group`             |      |                                  | Sandbox group (on `sandbox` / `sandboxgroup` sub-commands) |
+| `--region`            |      | `ACA_REGION`                     | Data plane region |
+| `--output`            | `-o` |                                  | Output format: `table` (default) or `json` |
+| `--managed-identity`  |      | `ACA_SANDBOX_MANAGED_IDENTITY`   | `system` or a client-id UUID |
+| `--verbose`           |      |                                  | HTTP traces and resolved config |
+| `--debug`             |      |                                  | Verbose + transport details (may log secrets) |
+| `--help`              | `-h` |                                  | Show help |
+| `--version`           | `-V` |                                  | Print version (top-level only) |
+
+Sandbox lookup flags (on commands that target a sandbox):
+
+| Flag | Short | Description |
+|---|---|---|
+| `--id`       |      | Target by UUID |
+| `--selector` | `-l` | Target by label selector `"k=v,k2=v2"` |
+
+Other command-specific short forms:
+
+| Flag | Short | Used by |
+|---|---|---|
+| `--command` | `-c` | `aca sandbox exec`, `aca sandbox shell` |
+
+---
+
+## Environment variables
+
+Every global flag has an env-var equivalent. Set them once in your shell
+and skip the flags.
+
+| Env var | Equivalent flag |
+|---|---|
+| `ACA_SUBSCRIPTION`              | `-s`, `--subscription` |
+| `ACA_RESOURCE_GROUP`            | `-g`, `--resource-group` |
+| `ACA_SANDBOX_GROUP`             | `--sandbox-group` |
+| `ACA_REGION`                    | `--region` |
+| `ACA_SANDBOX_MANAGED_IDENTITY`  | `--managed-identity` |
+
+Env wins over CLI config but loses to an explicit flag. See
+[Config → Precedence](#precedence) below.
+
+---
+
+## Config
+
+`aca` config lives at `~/.aca/config.json` and has two user-facing sections.
+
+Stop typing `-s … -g … --sandbox-group …` on every command. Set once,
+work for the rest of the session — with a precedence model that lets CI
+override anything via env vars without editing files.
+
+### Sections
+
+| Section | What goes there |
+|---|---|
+| **Shared Defaults** | Subscription, resource group, region — used by every command that doesn't override them. |
+| **Sandbox** | Sandbox-specific keys: sandbox group, auto-resume behavior, current sandbox, managed identity, audience, allowed regions, and per-section overrides for sub/RG/region. |
+
+### See your current config
+
+```bash
+aca config show
+```
+
+Sample output:
+
+```
+Configuration:
+  Shared Defaults:
+    subscription     a59d7183-…
+    resource_group   my-rg
+    region           westus2
+
+  Sandbox:
+    subscription     (inherited)
+    resource_group   (inherited)
+    region           westus2
+    group            my-sandbox-group
+    auto_resume      true
+    current_sandbox  (not set)
+    managed_identity (not set)
+    audience         (not set)
+
+Config file: ~/.aca/config.json
+```
+
+`(inherited)` means the Sandbox section inherits from Shared Defaults for that key.
+
+### Set Shared Defaults
+
+```bash
+aca config set \
+  -s <SUB_ID> \
+  -g <RG> \
+  --sandbox-group <GROUP> \
+  --region westus2
+```
+
+| Flag | Effect |
+|---|---|
+| `-s`, `--subscription` | Default subscription for all commands |
+| `-g`, `--resource-group` | Default resource group |
+| `--region` | Default data-plane region |
+| `--sandbox-group` | Default sandbox group name |
+
+### Set Sandbox-specific config
+
+```bash
+aca config sandbox set \
+  --group my-sandbox-group \
+  --auto-resume true \
+  --sandbox <UUID>
+```
+
+| Flag | Effect |
+|---|---|
+| `-s`, `--subscription` | Override Shared subscription for sandbox commands only |
+| `-g`, `--resource-group` | Override Shared resource group for sandbox commands only |
+| `--region` | Override Shared region for sandbox commands only |
+| `--group` | Default sandbox group name |
+| `--auto-resume true\|false` | Auto-resume a suspended sandbox before operations |
+| `--managed-identity system\|<CLIENT_ID>` | Use a managed identity for auth |
+| `--audience <URL>` | Override OAuth audience/scope |
+| `--sandbox <UUID>` | "Current" sandbox ID. Pass `""` to clear |
+| `--add-region <REGION>` / `--remove-region <REGION>` | Add/remove a region from the allowed list (repeatable) |
+
+When `auto_resume` is `true`, suspended sandboxes resume automatically
+when you `exec` into them.
+
+### Precedence
+
+For any setting, the CLI resolves in this order (highest wins):
+
+1. **Command-line flag** (e.g. `-s <X>`)
+2. **Environment variable** (e.g. `ACA_SUBSCRIPTION=<X>`)
+3. **Sandbox-specific config**
+4. **Shared Defaults config**
+
+---
+
+## `doctor`
+
+`aca doctor` runs 8 prerequisite/config/RBAC checks and tells you what's wrong.
+
+```bash
+aca doctor
+```
+
+Sample output (all green):
+
+```
+✓ Azure CLI found
+✓ Azure CLI logged in
+✓ Subscription: a59d7183-… (config)
+✓ Resource group: my-rg (config)
+✓ Sandbox group: my-sandbox-group (config: sandbox)
+✓ Region: westus2 (config: sandbox)
+✓ Sandbox group 'my-sandbox-group' exists in Azure
+✓ Container Apps SandboxGroup Data Owner role assigned
+
+aca 1.0.0-beta.1 — all checks passed
+```
+
+Each line shows **where the value came from** — `(config)`,
+`(config: sandbox)`, `(env)`, `(flag)` — gold when debugging precedence.
+
+### What each check verifies, and how to fix it
+
+| Check | Means | Fix |
+|---|---|---|
+| Azure CLI found        | `az` is on `PATH` | Install Azure CLI |
+| Azure CLI logged in    | `az account show` succeeds | `az login` |
+| Subscription           | Resolves a default subscription | `aca config set -s <ID>` or `az account set` |
+| Resource group         | Resolves a default RG | `aca config set -g <RG>` |
+| Sandbox group          | Resolves a default sandbox group | `aca config sandbox set --group <NAME>` |
+| Region                 | Resolves a default region | `aca config sandbox set --region <REGION>` |
+| Sandbox group exists   | The group resource is found in Azure | `aca sandboxgroup create --name <NAME> --location <REGION> --set-config` |
+| Data Owner role        | Caller has `Container Apps SandboxGroup Data Owner` on the group | `aca sandboxgroup role create --role "Container Apps SandboxGroup Data Owner" --principal-id $(az ad signed-in-user show --query id -o tsv)` |
+
+---

package/extensions/enact-repo/skills/aca-sandboxes/references/response-cues.md

@@ -0,0 +1,71 @@
+# Response cues and redirects
+
+Non-negotiable guidance for shaping a response: what each user intent must include, when to refuse and redirect, and worked examples to try.
+
+## Required cues per response type
+
+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 [install.md](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"`, `--label name=dev --label role=worker` (repeatable; **not** `--labels`). 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 --rule "*.github.com:Allow" --traffic-inspection Full`. Multiple `--rule "<pattern>:Allow"` flags accumulate. Inspect current policy with `aca sandbox egress show --id "$SANDBOX_ID"`. For production agent code, **always recommend `--default Deny`** with an explicit `--rule` allow-list. **Anti-cue:** do not invent flags for individual IPs or block-lists, and **not** `--host-allow` — the only supported shape is `--default Deny|Allow` plus repeated `--rule "<pattern>:Allow|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 published on PyPI as [`azure-containerapps-sandbox`](https://pypi.org/project/azure-containerapps-sandbox/). **Always preflight `uv` first** — if it's missing, install it from the upstream installer, then install the SDK. Bash: `command -v uv >/dev/null 2>&1 \|\| curl -LsSf https://astral.sh/uv/install.sh \| sh; uv pip install azure-containerapps-sandbox`. PowerShell: `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 ...`. 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 "Out of scope" 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. |
+
+## Out of scope — 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](https://learn.microsoft.com/azure/developer/azure-developer-cli/). 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](https://learn.microsoft.com/cli/azure/acr). 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.
+
+## 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` |

package/extensions/enact-repo/skills/aca-sandboxes/references/scenarios.md

@@ -0,0 +1,219 @@
+# Scenarios — when sandboxes shine
+
+Composed patterns that combine multiple sandbox capabilities. Each
+entry has a "when to use" and a minimal command sketch.
+
+---
+
+## 1. Web apps
+
+**When:** you have a web server and want a public URL in under a minute
+without provisioning ingress, certs, or a load balancer.
+
+**Sketch:**
+
+```bash
+SBX=$(aca sandbox create --disk ubuntu -o json | jq -r .id)
+
+# Upload + start
+aca sandbox fs write --id $SBX --path /app/server.py --file ./server.py
+aca sandbox exec --id $SBX -c "nohup uv run /app/server.py > /tmp/srv.log 2>&1 &"
+
+# Expose
+URL=$(aca sandbox port add --id $SBX --port 8080 --anonymous -o json | jq -r .url)
+echo "$URL"
+```
+
+Variants:
+
+- **simple-anonymous** — open to the internet (above).
+- **authenticated** — Entra-gated port (omit `--anonymous`).
+
+---
+
+## 2. Coding agents in a sandbox
+
+**When:** you want to run Copilot CLI, Claude Code, Codex, or any other
+coding agent in an isolated VM with deny-default egress, so the agent
+can only reach the endpoints you allow.
+
+**Sketch:**
+
+```bash
+# Per-task sandbox with deny-default egress + allow-list
+SBX=$(aca sandbox create --disk ubuntu --label task=copilot-run -o json | jq -r .id)
+aca sandbox egress set --id $SBX \
+  --default Deny \
+  --rule "api.githubcopilot.com:Allow" \
+  --rule "*.githubusercontent.com:Allow"
+
+aca sandbox exec --id $SBX -c "curl -fsSL https://github.com/cli/cli/releases/.../gh.tar.gz | tar -xz && ./gh ..."
+```
+
+Token-swap (inject the agent's auth header on egress, so the token
+never lands in the sandbox filesystem) — via the YAML policy:
+
+```bash
+aca sandbox egress init > egress-policy.yaml
+# edit egress-policy.yaml: add a rule with host: api.githubcopilot.com
+# and a header transform Authorization=Bearer <TOKEN>
+aca sandbox egress apply --id $SBX --file egress-policy.yaml
+```
+
+---
+
+## 3. Code interpreter
+
+**When:** an LLM generates code in a loop — generate, run, observe,
+iterate — and you need a fresh isolated environment per session.
+
+**Sketch:**
+
+```bash
+SBX=$(aca sandbox create --disk ubuntu --label kind=interpreter -o json | jq -r .id)
+
+# Loop:
+#   1. LLM emits code
+#   2. write -> exec -> capture stdout/stderr
+#   3. feed back into prompt
+aca sandbox fs write --id $SBX --path /tmp/step.py --file ./step.py
+aca sandbox exec --id $SBX -c "uv run /tmp/step.py" -o json
+```
+
+Snapshot between turns so you can rewind:
+
+```bash
+aca sandbox snapshot --id $SBX --name turn-3
+```
+
+---
+
+## 4. Swarms
+
+**When:** one orchestrator wants to fan work out across N worker
+sandboxes (rendering, scraping, eval, batch inference).
+
+**Sketch:**
+
+```bash
+# Orchestrator sandbox spawns workers in the same group via the
+# group's managed identity (no secrets needed inside the sandbox).
+BATCH_ID="batch-$(date +%s)"
+for i in $(seq 1 10); do
+  aca sandbox create --disk ubuntu \
+    --label role=worker --label batch=$BATCH_ID \
+    --no-wait
+done
+
+# Fan-out work by selector
+aca sandbox list -l "role=worker,batch=$BATCH_ID" -o json \
+  | jq -r '.[].id' \
+  | xargs -I{} -P 10 aca sandbox exec --id {} -c "./run-shard.sh"
+
+# Clean up — selector delete only matches one sandbox; iterate.
+aca sandbox list -l "role=worker,batch=$BATCH_ID" -o json \
+  | jq -r '.[].id' \
+  | xargs -I{} aca sandbox delete --id {} --yes
+```
+
+Add a shared AzureBlob volume to the group for durable scratch space
+across workers (`aca sandboxgroup volume …`).
+
+---
+
+## 5. Computer-use
+
+**When:** an LLM with computer-use capability drives a real browser
+inside a sandbox (form filling, web research, end-to-end tests). Watch
+live via noVNC.
+
+**Sketch:**
+
+```bash
+SBX=$(aca sandbox create --disk ubuntu --cpu 2000m --memory 4096Mi -o json | jq -r .id)
+aca sandbox exec --id $SBX -c "apt-get install -y chromium x11vnc novnc && start-desktop.sh"
+
+# Expose noVNC for the human to watch
+aca sandbox port add --id $SBX --port 6080 --anonymous
+```
+
+The LLM (Azure OpenAI `computer-use-preview` or similar) drives the
+browser via screenshot + click/keys actions sent through `sandbox exec`.
+
+---
+
+## 6. MCP hosting
+
+**When:** you want to host a Model Context Protocol (MCP) server in a
+sandbox for AI clients to connect to over HTTPS.
+
+**Sketch (public via `port add`):**
+
+```bash
+SBX=$(aca sandbox create --disk ubuntu -o json | jq -r .id)
+aca sandbox exec --id $SBX -c "npx -y @excalidraw/mcp-server &"
+aca sandbox port add --id $SBX --port 3000 --anonymous
+```
+
+**Sketch (Dev Tunnels, no inbound port):**
+
+```bash
+SBX=$(aca sandbox create --disk ubuntu -o json | jq -r .id)
+aca sandbox exec --id $SBX -c "npx -y @excalidraw/mcp-server &"
+aca sandbox exec --id $SBX -c "devtunnel host -p 3000 --allow-anonymous"
+# Tunnel URL is printed by devtunnel; share it with the MCP client.
+```
+
+---
+
+## 7. Data processing
+
+**When:** producer/consumer pipelines that need shared scratch space
+across short-lived sandboxes.
+
+**Sketch:**
+
+```bash
+# Create a group-level shared volume (default type: AzureBlob)
+aca sandboxgroup volume create --name shared --type AzureBlob
+
+# Create the sandboxes, then mount the volume into each
+SBX_P=$(aca sandbox create --disk ubuntu --label role=producer -o json | jq -r .id)
+aca sandbox mount --id $SBX_P --volume shared --path /data
+
+SBX_C=$(aca sandbox create --disk ubuntu --label role=consumer -o json | jq -r .id)
+aca sandbox mount --id $SBX_C --volume shared --path /data
+```
+
+Producers write to `/data/inbox/`, consumers drain it. Sandboxes
+suspend when idle and pay nothing.
+
+---
+
+## 8. Developer workflows
+
+**When:** PR builds, ephemeral CI, on-demand dev environments. A fresh
+sandbox per PR or per developer, deleted on close.
+
+**Sketch:**
+
+```bash
+SBX=$(aca sandbox create --disk ubuntu \
+  --label pr=$PR_NUMBER --label kind=ci -o json | jq -r .id)
+aca sandbox fs write --id $SBX --path /repo.tar.gz --file ./repo.tar.gz
+aca sandbox exec --id $SBX -c "cd /tmp && tar xzf /repo.tar.gz && make test"
+aca sandbox delete --id $SBX --yes
+```
+
+---
+
+## 9. Sandbox-backed agent frameworks
+
+**When:** you're using an agent framework (OpenAI Agents SDK, Claude
+Managed Agents, LangChain) and want sandboxes to be the tool-execution
+backend instead of the local machine.
+
+**Sketch:** the framework's "tool" implementation calls
+`aca sandbox exec --id $SBX -c "<tool-cmd>"` (or the equivalent API)
+and returns the stdout/stderr to the agent. Each conversation gets its
+own sandbox, snapshotted between turns for rewind.

package/extensions/enact-repo/skills/aca-sandboxes/version.json

@@ -0,0 +1,4 @@
+{
+  "name": "aca-sandboxes",
+  "version": "0.0.5-beta"
+}