Azure Container Apps Sandbox Client Library for Python

⚠️ Preview — This SDK is in preview. The API surface may change without notice.

Data-plane and control-plane SDK for Azure Container Apps sandboxes.

Isolated MicroVMs

Secure, isolated compute environments with sub-second startup.

• Hardware-isolated microVM boundary — fully separated from host, platform, and other sandboxes
• Snapshot-based suspend/resume preserving full memory and disk state across sessions
• Per-sandbox network egress policy with deny-by-default posture for untrusted code

What you can build

• Traditional Apps. Lift-and-shift workloads that need stateful compute, custom kernels, or per-tenant isolation without rewriting.
• AI Apps & Agents. Persistent, isolated workspaces that survive across task boundaries. Suspend between turns, resume with full context.
• Code execution. Run untrusted code in seconds with strong isolation. Capture state with snapshots, replay deterministically.
• Dev environments. Per-user compute that scales from zero to hundreds on demand and preserves state across sessions.
• Many more… CI runners, browser automation, data prep, reproducible experiments — anywhere a fast, isolated VM helps.

Installation

pip install azure-containerapps-sandbox

Quick start

import uuid
from azure.identity import DefaultAzureCredential
from azure.mgmt.resource.resources import ResourceManagementClient
from azure.mgmt.authorization import AuthorizationManagementClient
from azure.containerapps.sandbox import (
    SandboxGroupManagementClient,
    SandboxGroupClient,
    endpoint_for_region,
)

credential = DefaultAzureCredential()
subscription_id = "<your-subscription-id>"  # az account show --query id -o tsv
principal_id = "<your-principal-id>"  # az ad signed-in-user show --query id -o tsv
resource_group = "my-rg"
sandbox_group = "my-sandbox-group"
region = "eastus2"

# 1. Create resource group
resource_client = ResourceManagementClient(credential, subscription_id)
resource_client.resource_groups.create_or_update(resource_group, {"location": region})

# 2. Create sandbox group
mgmt = SandboxGroupManagementClient(
    credential, subscription_id=subscription_id, resource_group=resource_group,
)
mgmt.create_group(sandbox_group, location=region)

# 3. Grant data-plane access
auth_client = AuthorizationManagementClient(credential, subscription_id)
scope = f"/subscriptions/{subscription_id}/resourceGroups/{resource_group}"
role_def = next(auth_client.role_definitions.list(
    scope, filter="roleName eq 'Container Apps SandboxGroup Data Owner'"
))
auth_client.role_assignments.create(scope, uuid.uuid4(), {
    "role_definition_id": role_def.id,
    "principal_id": principal_id,
    "principal_type": "User",
})

# 4. Connect to data plane and create a sandbox
client = SandboxGroupClient(
    endpoint_for_region(region), credential,
    subscription_id=subscription_id,
    resource_group=resource_group,
    sandbox_group=sandbox_group,
)
sandbox = client.begin_create_sandbox(disk="ubuntu").result()

# 5. Run a command
result = sandbox.exec("echo hello world && uname -a")
print(result.stdout)

# 6. Clean up
sandbox.delete()
mgmt.delete_group(sandbox_group)
client.close()
mgmt.close()

Authentication

Uses DefaultAzureCredential from azure-identity, which automatically picks up az login, managed identity, environment variables, etc.

Port access control

Restrict which inbound client IPs can reach a port with a source-IP allow/deny policy. Rules match by CIDR range — the lowest priority is evaluated first, and default_action decides traffic that matches no rule.

from azure.containerapps.sandbox import (
    PortIpAccessControl,
    PortIpAccessControlRule,
)

# Allow only an internal range; deny everything else.
acl = PortIpAccessControl(
    default_action="Deny",
    rules=[
        PortIpAccessControlRule(
            name="office",
            action="Allow",
            priority=10,
            source_cidrs=["10.0.0.0/8"],
        ),
    ],
)

# Open a port with the policy on an existing sandbox.
sandbox.add_port(8443, ip_access_control=acl)

Set the same policy at sandbox creation by passing AddPortRequest to ports= (it also works with sandbox.update_ports([...])):

from azure.containerapps.sandbox import AddPortRequest

sandbox = client.begin_create_sandbox(
    disk="ubuntu",
    ports=[AddPortRequest(port=8443, ip_access_control=acl)],
).result()

Read the effective policy back from a response port via SandboxPort.ip_access_control. The async aio clients accept the identical ip_access_control keyword.

The policy is validated client-side before it is sent; an invalid one raises ValueError. Constraints mirror the service:

• At most 10 rules, each with 1–10 source CIDRs.
• Each CIDR must be network-aligned (host bits zero) — 10.0.0.0/8 is valid, 10.0.0.5/8 is rejected.
• priority is 0–1000; names and priorities must be unique (names case-insensitive). Lower priority is evaluated first.