Quick start

CLI

Install the aca CLI, provision a sandbox group, launch a sandbox, run a command, and tear it all down.

Before you begin

• An Azure subscription with permission to create resource groups.
• Azure CLI (az) installed. aca delegates auth to az login.
• A shell: Bash on Linux/macOS, PowerShell on Windows. (WSL and Git Bash also work.)

Install the aca CLI

Bash

curl -fsSL https://aka.ms/aca-cli-install | sh

PowerShell

irm https://aka.ms/aca-cli-install-ps | iex

Smoke-test the install:

Bash

aca --version
# aca 1.0.0-preview.4

PowerShell

aca --version
# aca 1.0.0-preview.4

Log in to Azure

Run az login once per shell. Subsequent commands reuse the same Azure CLI session.

Bash

az login

PowerShell

az login

Provision the resource group and sandbox group

Bash

SUBSCRIPTION_ID=$(az account show --query id -o tsv)

az group create \
  --name my-rg \
  --location westus2

aca sandboxgroup create \
  -g my-rg \
  --name my-sandbox-group \
  --location westus2 \
  -s "$SUBSCRIPTION_ID" \
  --set-config

PowerShell

$SubscriptionId = az account show --query id -o tsv

az group create `
  --name my-rg `
  --location westus2

aca sandboxgroup create `
  -g my-rg `
  --name my-sandbox-group `
  --location westus2 `
  -s $SubscriptionId `
  --set-config

note

--set-config saves the subscription, resource group, sandbox group, and region in aca config so you don't have to pass them on every subsequent command. Group creation also attempts to grant your signed-in user the Data Owner role; if that fails, aca doctor reports the missing access.

Verify with aca doctor

Bash

aca doctor

PowerShell

aca doctor

Create and run a sandbox

Tag the sandbox with a label at create time, then use -l (label selector) to target it from exec and delete — no need to capture the ID.

Bash

aca sandbox create \
  --disk ubuntu \
  --label name=my-first-sandbox

aca sandbox exec -l name=my-first-sandbox -c "echo 'Hello from ACA Sandbox.'"

aca sandbox delete -l name=my-first-sandbox --yes

PowerShell

aca sandbox create `
  --disk ubuntu `
  --label name=my-first-sandbox

aca sandbox exec -l name=my-first-sandbox -c "echo 'Hello from ACA Sandbox.'"

aca sandbox delete -l name=my-first-sandbox --yes

Teardown (optional)

Delete the sandbox group and the resource group:

Bash

aca sandboxgroup delete -g my-rg --name my-sandbox-group --yes
az group delete --name my-rg --yes --no-wait

PowerShell

aca sandboxgroup delete -g my-rg --name my-sandbox-group --yes
az group delete --name my-rg --yes --no-wait

Next steps

Install an agent skill

Let GitHub Copilot or Claude Code drive sandboxes through these same commands.

Learn more →

Create sandboxes

Sizes, env vars, labels, and YAML specs.

Learn more →

Open a shell

Drop into an interactive bash session for live debugging.

Learn more →