Skip to content

Commit 918fa72

Browse files
JennyLawranceJennyLawrance
authored
Merge pull request #1724 from microsoft/anganti-microsoft/skills-marketplace-sandboxes
Add skills marketplace with sandboxes skill
2 parents a49646d + d4ca2ee commit 918fa72

11 files changed

Lines changed: 1125 additions & 0 deletions

File tree

‎marketplace.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"name": "Azure-Container-Apps",
3+
"metadata": {
4+
"description": "Azure Container Apps skills marketplace — self-contained skills for coding agents (Copilot CLI, Claude Code).",
5+
"version": "0.1.0"
6+
},
7+
"owner": {
8+
"name": "Microsoft",
9+
"url": "https://github.com/microsoft/azure-container-apps"
10+
},
11+
"plugins": [
12+
{
13+
"name": "sandboxes",
14+
"source": "./plugin",
15+
"description": "Sandboxes — hardware-isolated microVMs with snapshot/resume, scale-to-zero. Driven by the `aca` CLI; Python SDK also available.",
16+
"version": "0.0.1-beta",
17+
"skills": [
18+
"./plugin/skills/sandboxes"
19+
]
20+
}
21+
]
22+
}

‎plugin/.claude-plugin/plugin.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "Azure-Container-Apps",
3+
"description": "Azure Container Apps skills marketplace — sandboxes (and more, coming soon).",
4+
"version": "0.0.1-beta",
5+
"author": {
6+
"name": "Microsoft",
7+
"url": "https://www.microsoft.com"
8+
},
9+
"homepage": "https://github.com/microsoft/azure-container-apps",
10+
"repository": "https://github.com/microsoft/azure-container-apps",
11+
"license": "MIT",
12+
"keywords": [
13+
"azure",
14+
"container-apps",
15+
"sandbox",
16+
"microvm",
17+
"ai-agents",
18+
"aca"
19+
],
20+
"skills": "./skills/"
21+
}

‎plugin/.plugin/plugin.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "Azure-Container-Apps",
3+
"description": "Azure Container Apps skills marketplace — sandboxes (and more, coming soon).",
4+
"version": "0.0.1-beta",
5+
"author": {
6+
"name": "Microsoft",
7+
"url": "https://www.microsoft.com"
8+
},
9+
"homepage": "https://github.com/microsoft/azure-container-apps",
10+
"repository": "https://github.com/microsoft/azure-container-apps",
11+
"license": "MIT",
12+
"keywords": [
13+
"azure",
14+
"container-apps",
15+
"sandbox",
16+
"microvm",
17+
"ai-agents",
18+
"aca"
19+
],
20+
"skills": "./skills/"
21+
}

‎plugin/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Azure Container Apps Plugins Marketplace
2+
3+
Skills for Azure Container Apps — install once, drive `aca` from natural language
4+
in your coding agent.
5+
6+
## Install
7+
8+
### GitHub Copilot CLI
9+
10+
```bash
11+
# Add as a plugin marketplace
12+
/plugin marketplace add microsoft/azure-container-apps
13+
14+
# Install all skills
15+
/plugin install sandboxes@Azure-Container-Apps
16+
```
17+
18+
### Claude Code
19+
20+
```bash
21+
claude plugin add microsoft/azure-container-apps
22+
```

‎plugin/skills/sandboxes/SKILL.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
name: sandboxes
3+
description: |
4+
Sandboxes — hardware-isolated microVMs on Azure Container Apps for
5+
running AI-generated code, coding agents, MCP servers, web apps, and
6+
ephemeral workloads. Snapshot/resume, scale-to-zero, sub-second
7+
startup, deny-default egress. Driven by the `aca` CLI (auth delegates
8+
to `az login`).
9+
10+
Use when the user wants to: create or manage sandbox groups and
11+
sandboxes; exec commands or open an interactive shell; read/write
12+
files; expose ports; snapshot, stop, resume, commit to a disk, or
13+
mount volumes; tighten egress; manage secrets, managed identity,
14+
labels; apply YAML specs; or run scenarios like web apps, coding
15+
agents, code interpreter, swarms, sandbox inception, computer-use,
16+
MCP hosting, data processing, or developer workflows.
17+
18+
Triggers: "create sandbox", "sandbox group", "aca cli", "aca
19+
sandbox", "azure container apps sandbox", "ACA sandbox", "microVM",
20+
"isolated VM", "run untrusted code", "exec in sandbox", "sandbox
21+
shell", "copy files to sandbox", "sandbox port", "sandbox snapshot",
22+
"commit sandbox to disk", "sandbox volume", "mount volume sandbox",
23+
"suspend sandbox", "resume sandbox", "sandbox lifecycle",
24+
"auto-suspend sandbox", "sandbox secret", "sandbox managed identity",
25+
"sandbox labels", "sandbox apply yaml", "egress deny", "egress
26+
allow-list", "code interpreter", "agent swarm", "sandbox inception",
27+
"coding agent sandbox", "computer use sandbox", "host mcp".
28+
---
29+
30+
# Sandboxes
31+
32+
Hardware-isolated microVMs on Azure Container Apps. Snapshot/resume,
33+
scale-to-zero, sub-second startup, deny-default egress. This skill
34+
drives sandboxes through the **`aca` CLI** — one command surface, no
35+
ambiguity. Self-contained — everything is under `references/` in this
36+
folder.
37+
38+
## What it is
39+
40+
- **Resource type:** `Microsoft.App/SandboxGroups` (preview).
41+
- **Isolation:** each sandbox is its own microVM, safe for untrusted code.
42+
- **Startup:** sub-second from a prewarmed pool; suspend/resume preserves
43+
full memory + disk.
44+
- **Scale:** zero to thousands; pay nothing when idle.
45+
- **Auth:** `aca` delegates to `az login` — same identity, same MFA.
46+
47+
> ⚠️ **The `az` CLI has no sandbox commands.** Sandbox groups and
48+
> sandboxes are managed by `aca` — **not** by `az containerapp …`. The
49+
> `az containerapp` commands are for the older Apps / Jobs surface and
50+
> do not touch sandboxes. If you see `az containerapp sandbox …` in a
51+
> snippet, it's wrong.
52+
53+
## Get started
54+
55+
| | Where |
56+
|---|---|
57+
| **Install** | [references/install.md](references/install.md) |
58+
| **Prerequisites** | [references/prerequisites.md](references/prerequisites.md) |
59+
| **Quick start** | [references/quickstart.md](references/quickstart.md) |
60+
| **Full CLI reference** | [references/reference.md](references/reference.md) |
61+
| **Scenario recipes** | [references/scenarios.md](references/scenarios.md) |
62+
63+
After install, always confirm setup with `aca doctor` — it resolves
64+
subscription / RG / group / region / role and tells you which check
65+
is red.
66+
67+
## Capabilities
68+
69+
Everything the platform exposes. Each row is the starting point — open
70+
[references/reference.md](references/reference.md) for full flags and
71+
options.
72+
73+
> Command rows below show only the **shape**. In real invocations:
74+
> - every `aca sandbox <verb>` takes `--id <sandbox-id>`;
75+
> - every `aca sandboxgroup <noun> <verb>` mutation takes `--name <group>`
76+
> (or relies on the default group set via `--set-config`);
77+
> - omit these from copies into the shell and you'll get a CLI parse error.
78+
79+
| # | Capability | What it does | `aca` CLI |
80+
|----|---------------------------|------------------------------------------------------------------------------|-----------|
81+
| 00 | **Sandbox groups** | Provision, list/get, assign Data Owner role, tear down. | `aca sandboxgroup create / list / get / role create / delete` |
82+
| 01 | **Sandboxes** | Create, list, get, delete; cpu/memory/labels/env; parallel. | `aca sandbox create / list / get / delete` (+ `--cpu --memory --labels --env`) |
83+
| 02 | **Snapshots** | Freeze a running sandbox; boot new ones from that point. | `aca sandbox snapshot --id <id> --name X` · `aca sandbox create --snapshot X` |
84+
| 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) |
85+
| 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` |
86+
| 05 | **Lifecycle** | Stop/resume; auto-suspend after idle; auto-delete after TTL. | `aca sandbox stop / resume` · `aca sandbox lifecycle set --auto-suspend 60` |
87+
| 06 | **Ports** | Expose an HTTP port; anonymous or Entra-gated; revoke. | `aca sandbox port add --port 8080 [--anonymous]` · `port list / remove` |
88+
| 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) |
89+
| 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` |
90+
| 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` |
91+
| 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` |
92+
| 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` |
93+
| 12 | **Interactive shell** | Real PTY into a running sandbox. | `aca sandbox shell --id <id>` |
94+
| 13 | **YAML spec / `apply`** | Declarative infra-as-code: `init`, `validate`, `apply`, `schema`. | `aca sandbox init > sandbox.yaml` · `validate` · `apply --file sandbox.yaml` |
95+
| 14 | **`aca doctor`** | Diagnose subscription / RG / group / region / role. | `aca doctor` |
96+
97+
## Scenarios
98+
99+
Composed patterns that combine the capabilities above. Full sketches
100+
in [references/scenarios.md](references/scenarios.md).
101+
102+
- **Web apps** — start a server, expose a port anonymously, hit the URL.
103+
- **Coding agents in a sandbox** — run Copilot CLI / Claude Code / Codex
104+
with deny-default egress and (optionally) token-swap rules.
105+
- **Code interpreter** — LLM generates → exec → observe → iterate;
106+
snapshot between turns for rewind.
107+
- **Swarms** — orchestrator fans work across N worker sandboxes by
108+
label selector.
109+
- **Sandbox inception** — orchestrator runs *inside* a sandbox and uses
110+
its managed identity to drive a separate worker group. No credentials
111+
in agent code.
112+
- **Computer-use** — LLM drives a real browser; watch live via noVNC.
113+
- **MCP hosting** — host an MCP server in a sandbox; expose via port or
114+
Dev Tunnel.
115+
- **Data processing** — producer/consumer pipelines on shared
116+
`AzureBlob` volumes.
117+
- **Developer workflows** — PR builds, ephemeral CI, on-demand dev envs.
118+
119+
## Python SDK (separate)
120+
121+
An early-access Python SDK (`azure-containerapps-sandbox`) is also
122+
available if you'd rather drive sandboxes from service code instead of
123+
the CLI. It is **out of scope for this skill** — when the user asks for
124+
Python, point them at the upstream README and stop:
125+
126+
> https://github.com/microsoft/azure-container-apps/blob/main/docs/early/python-sdk/README.md
127+
128+
Mixing CLI and SDK in the same answer confuses things. Pick one.

‎plugin/skills/sandboxes/references/install.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Install the `aca` CLI
2+
3+
The `aca` CLI is the primary surface for sandboxes. It delegates
4+
authentication to the Azure CLI (`az login`).
5+
6+
## Linux / macOS
7+
8+
```bash
9+
curl -fsSL https://raw.githubusercontent.com/microsoft/azure-container-apps/main/docs/early/aca-cli/install.sh | sh
10+
```
11+
12+
Pin a specific version:
13+
14+
```bash
15+
curl -fsSL https://raw.githubusercontent.com/microsoft/azure-container-apps/main/docs/early/aca-cli/install.sh \
16+
| ACA_VERSION=aca-cli-v0.1.0-early-access sh
17+
```
18+
19+
## Windows (PowerShell)
20+
21+
```powershell
22+
irm https://raw.githubusercontent.com/microsoft/azure-container-apps/main/docs/early/aca-cli/install.ps1 | iex
23+
```
24+
25+
Pin a specific version:
26+
27+
```powershell
28+
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/azure-container-apps/main/docs/early/aca-cli/install.ps1))) -Version aca-cli-v0.1.0-early-access
29+
```
30+
31+
## Verify
32+
33+
```bash
34+
aca --version
35+
# aca 1.0.0-beta.1
36+
```
37+
38+
Then log in and run the doctor:
39+
40+
```bash
41+
az login
42+
aca doctor
43+
```
44+
45+
## Uninstall
46+
47+
```bash
48+
# Linux / macOS
49+
curl -fsSL https://raw.githubusercontent.com/microsoft/azure-container-apps/main/docs/early/aca-cli/install.sh | sh -s -- --uninstall
50+
```
51+
52+
```powershell
53+
# Windows
54+
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/azure-container-apps/main/docs/early/aca-cli/install.ps1))) -Uninstall
55+
```
56+
57+
## Supported platforms
58+
59+
| Platform | Architecture |
60+
|---|---|
61+
| Linux | x64 |
62+
| macOS | ARM64 |
63+
| Windows | x64 |

‎plugin/skills/sandboxes/references/prerequisites.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# CLI prerequisites
2+
3+
## Accounts and access
4+
5+
- **Azure subscription** — one you can create resource groups in.
6+
[Create one for free](https://azure.microsoft.com/pricing/purchase-options/azure-account).
7+
- **Microsoft Entra ID account** — personal Microsoft accounts are **not** supported.
8+
- **Role** — to create sandboxes inside a group you need the
9+
`Container Apps SandboxGroup Data Owner` role on the group. The
10+
[quickstart](quickstart.md) shows how to grant it to yourself.
11+
12+
## Tools
13+
14+
- **[Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)** installed and logged in (`az login`).
15+
The `aca` CLI delegates auth to `az login` — same identity, same MFA,
16+
same conditional-access policies.
17+
- **An Azure subscription with a resource group.**
18+
- **`aca` CLI** — installed in one line; see [install.md](install.md).
19+
- **A shell** — Bash on Linux/macOS; PowerShell or Bash (Git Bash / WSL) on Windows.
20+
21+
## Supported platforms
22+
23+
| Platform | Architecture |
24+
|---|---|
25+
| Linux | x64 |
26+
| macOS | ARM64 |
27+
| Windows | x64 |
28+
29+
## Region
30+
31+
Sandboxes are a preview resource type. Start with a well-supported
32+
region such as `eastus2` or `westus2`. If a region rejects the group
33+
create, try another — `aca` will tell you which region the API rejected.
34+
35+
## Doctor checklist
36+
37+
`aca doctor` runs all of the following — green across the board means
38+
you are ready to create sandboxes:
39+
40+
1. Azure CLI found on `PATH`.
41+
2. Azure CLI is logged in (`az account show` succeeds).
42+
3. A default subscription is resolved (flag, env, or config).
43+
4. A default resource group is resolved.
44+
5. A default sandbox group is resolved.
45+
6. A default region is resolved.
46+
7. The sandbox group exists in Azure.
47+
8. The caller has the `Container Apps SandboxGroup Data Owner` role on the group.
48+
49+
Each line in `aca doctor` output also tells you **where** the value came
50+
from — `(flag)`, `(env)`, `(config: sandbox)`, or `(config)` — which is
51+
invaluable when debugging precedence. See
52+
[reference.md](reference.md#config) for the precedence model.

0 commit comments

Comments
 (0)