Skip to main content
Quick start

TypeScript SDK

Create a sandbox group and run a command with the TypeScript SDK.

Before you begin
  • An Azure subscription with permission to create resource groups and role assignments.
  • Azure CLI (az) installed.
  • Node.js 20.6 or later.
  • Bash or PowerShell.

Install and configure the SDK​

Create an empty project directory and open a shell in it. Install the sandbox package, its authentication dependency, and the TypeScript tools used in this quickstart.

npm init -y
npm pkg set type=module
npm install @azure/containerapps-sandbox @azure/identity
npm install --save-dev typescript tsx

# Sign in so DefaultAzureCredential can use your Azure CLI identity.
az login

AZURE_SUBSCRIPTION_ID=$(az account show --query id -o tsv)
AZURE_RESOURCE_GROUP=my-rg
AZURE_SANDBOX_GROUP=my-sandbox-group
AZURE_REGION=eastus2
AZURE_PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)

az group create --name "$AZURE_RESOURCE_GROUP" --location "$AZURE_REGION"

cat > .env <<EOF
AZURE_SUBSCRIPTION_ID=$AZURE_SUBSCRIPTION_ID
AZURE_RESOURCE_GROUP=$AZURE_RESOURCE_GROUP
AZURE_SANDBOX_GROUP=$AZURE_SANDBOX_GROUP
AZURE_REGION=$AZURE_REGION
AZURE_PRINCIPAL_ID=$AZURE_PRINCIPAL_ID
EOF

DefaultAzureCredential uses the identity from az login. The .env file supplies the resource names to the TypeScript files in the remaining steps.

Create a sandbox group​

The package has two clients. ContainerAppsSandboxManagementClient manages sandbox groups through the Azure Resource Manager control plane. SandboxGroupClient manages sandboxes and related resources through the data plane.

Save this control-plane setup as setup.ts:

import { DefaultAzureCredential } from "@azure/identity";
import { ContainerAppsSandboxManagementClient } from "@azure/containerapps-sandbox";

const credential = new DefaultAzureCredential();
const subscriptionId = process.env.AZURE_SUBSCRIPTION_ID!;
const resourceGroup = process.env.AZURE_RESOURCE_GROUP!;
const sandboxGroup = process.env.AZURE_SANDBOX_GROUP!;
const region = process.env.AZURE_REGION!;

const managementClient = new ContainerAppsSandboxManagementClient(
  credential,
  subscriptionId,
);

const createGroupPoller = managementClient.sandboxGroups.beginCreateOrUpdate(
  resourceGroup,
  sandboxGroup,
  { location: region },
);
await createGroupPoller.pollUntilDone();

console.log(`Created sandbox group: ${sandboxGroup}`);

Run the setup, then grant your signed-in user data-plane access at the sandbox group scope.

set -a
source .env
set +a

npx tsx --env-file=.env setup.ts

az role assignment create \
  --role "Container Apps SandboxGroup Data Owner" \
  --assignee-object-id "$AZURE_PRINCIPAL_ID" \
  --assignee-principal-type User \
  --scope "/subscriptions/$AZURE_SUBSCRIPTION_ID/resourceGroups/$AZURE_RESOURCE_GROUP/providers/Microsoft.App/sandboxGroups/$AZURE_SANDBOX_GROUP"

Role assignments can take up to 60 seconds to propagate. If the next step returns a 403 response, wait a minute and retry.

Create and run a sandbox​

Save this data-plane lifecycle as main.ts:

import { DefaultAzureCredential } from "@azure/identity";
import { SandboxGroupClient, endpointForRegion } from "@azure/containerapps-sandbox";

const credential = new DefaultAzureCredential();
const groupClient = new SandboxGroupClient(
  credential,
  endpointForRegion(process.env.AZURE_REGION!),
  process.env.AZURE_SUBSCRIPTION_ID!,
  process.env.AZURE_RESOURCE_GROUP!,
  process.env.AZURE_SANDBOX_GROUP!,
);

const createSandboxPoller = groupClient.sandboxes.beginCreate({
  sourcesRef: {
    diskImage: { name: "ubuntu", isPublic: true },
  },
});
const sandbox = await createSandboxPoller.pollUntilDone();

try {
  const result = await groupClient.sandboxes.exec(sandbox.id, {
    command: "echo 'Hello from ACA Sandbox.'",
  });
  console.log(result.stdout);
} finally {
  await groupClient.sandboxes.delete(sandbox.id);
}

Run the file:

npx tsx --env-file=.env main.ts

Other operations​

SandboxGroupClient has operation groups for sandboxes, disk images, snapshots, volumes, secrets, ports, egress, and files. List operations return an asynchronous iterator, and begin* methods return a poller for long-running operations.

for await (const sandbox of groupClient.sandboxes.list()) {
  console.log(sandbox.id, sandbox.state);
}

Clean up​

Save the control-plane cleanup as teardown.ts:

import { DefaultAzureCredential } from "@azure/identity";
import { ContainerAppsSandboxManagementClient } from "@azure/containerapps-sandbox";

const credential = new DefaultAzureCredential();
const subscriptionId = process.env.AZURE_SUBSCRIPTION_ID!;
const resourceGroup = process.env.AZURE_RESOURCE_GROUP!;
const sandboxGroup = process.env.AZURE_SANDBOX_GROUP!;

const managementClient = new ContainerAppsSandboxManagementClient(
  credential,
  subscriptionId,
);

const deleteGroupPoller = managementClient.sandboxGroups.beginDelete(
  resourceGroup,
  sandboxGroup,
);
await deleteGroupPoller.pollUntilDone();

console.log(`Deleted sandbox group: ${sandboxGroup}`);

Run the cleanup, then delete the resource group created for this quickstart.

set -a
source .env
set +a

npx tsx --env-file=.env teardown.ts
az group delete --name "$AZURE_RESOURCE_GROUP" --yes --no-wait

Next steps​

Install an agent skill

Let GitHub Copilot or Claude Code manage sandboxes through prompts.

Learn more →

Create sandboxes

Configure resources, environment variables, labels, and parallel creation.

Learn more →

Suspend and resume

Keep memory and disk state while a sandbox is suspended.

Learn more →
Last updated on