Azure Container Apps Sandboxes overview

Azure Container Apps Sandboxes provide fast, secure, ephemeral compute environments with built-in suspend and resume capabilities. Sandboxes are a first-class resource type (Microsoft.App/SandboxGroups) in Container Apps, alongside apps, jobs, and dynamic sessions.

Create and manage sandbox environments

You can create and manage sandboxes in the Sandboxes portal or programmatically by using Azure Container Apps CLI or SDK.

Key characteristics of Container Apps Sandboxes

• Sub-second startup: Sandboxes boot from cached images in under a second, and resume from snapshots even faster.

• Strong isolation: Each sandbox runs in its own secure boundary, safe for untrusted code execution.

• Scale to zero: You pay no CPU or memory fees when sandboxes are stopped.

• Scale-out: The service bursts to thousands of concurrent sandboxes on demand.

• OCI container image support: Use the included platform managed images or bring your own container images as sandbox root filesystems.

• Suspend and resume: Snapshot full state including memory and disk, and resume later with sub-second restore times.

• Lifecycle control: You can manage the full sandbox lifecycle, including state snapshots, persistent storage, and networking policies (both egress and ingress).

When to use sandboxes

Use sandboxes when you need isolated compute environments with explicit lifecycle control, persistent state, or programmable access through SDKs.

Choose the right Container Apps compute option

Use the following table to select the Container Apps compute type that fits your workload.

Architecture

A sandbox group is a regional Azure Resource Manager (ARM) resource that can contain thousands of sandboxes. It provides a shared scope for disk images, snapshots, volumes, secrets, and managed identities.

Each sandbox is an isolated microVM that starts from a disk image or snapshot and can mount persistent data volumes. Sandboxes can be running or stopped. Stopped sandboxes don't incur compute charges, and snapshots can preserve memory and disk state for later restoration or cloning.

Managed ingress and egress proxies outside the sandbox handle network traffic, with VNet integration for outbound access to private resources and private endpoints for inbound access.

Management planes

Sandboxes use a two-plane architecture:

You create and manage sandbox groups through the ARM control plane. All operations on individual sandboxes and their resources go through the ACA Sandboxes data plane, scoped to a specific sandbox group.

Prerequisites

To create or manage sandboxes, you need the Azure role assignment Container Apps SandboxGroup Data Owner. Without this role, you can't perform sandbox operations. Assign this role at the sandbox group scope to limit access to that group, or at a parent resource group or subscription scope for broader access. Use the Azure portal or the Azure CLI.

Before running the following command, replace the placeholders surrounded by <> with your own values.

az role assignment create \
  --assignee "<USER_EMAIL_OR_OBJECT_ID>" \
  --role "Container Apps SandboxGroup Data Owner" \
  --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.App/sandboxGroups/<SANDBOX_GROUP_NAME>"

Key concepts

Sandbox groups

A sandbox group is the top-level management boundary for sandboxes. It's an Azure Resource Manager (ARM) resource that you create in a resource group and region. All sandboxes, disk images, snapshots, volumes, and secrets are scoped to a sandbox group.

Use sandbox groups to organize sandboxes by application, team, or environment.

Sandboxes

A sandbox is an individual isolated compute instance within a sandbox group. Each sandbox runs from a disk image or snapshot and has its own CPU, memory, disk, and network boundary.

You interact with sandboxes by executing commands, managing files, exposing ports, and controlling lifecycle state.

Disk images

Disk images are OCI container images converted for use as sandbox root filesystems. You can use public images or create private images from your own container registries.

Choose from the following disk image sources:

• Public images: Prebuilt and maintained by Microsoft, available to all sandbox groups.
• Container registry images: Pull from public or your private registries with optional authentication.

For more information, see Disk images.

Egress network control

Azure Container Apps Sandboxes are designed to run untrusted code. An egress proxy outside the sandbox enforces policies that allow or block outbound traffic by host and injects secrets without exposing them to sandbox code. Without a policy, outbound access is unrestricted. For more information, see Control egress.

Virtual network integration

Connect a sandbox group to your Azure virtual network (VNet) through a delegated subnet so sandboxes can reach private endpoints, peered networks, and on-premises resources. Select a group-level VNet connection when you create a sandbox. For more information, see VNet.

Ingress network control

Ingress lets clients access HTTP services running inside a sandbox, such as web apps, APIs, and development previews. Incoming requests to each exposed port's HTTPS URL are routed to the corresponding service inside the sandbox. You can add or remove exposed ports as needed. Each port can allow anonymous access or require Microsoft Entra ID authentication. For more information, see Expose ports.

Private endpoint

Use a private endpoint to reach exposed sandbox ports from a VNet, peered network, or on-premises network through VPN or ExpressRoute. For more information, see Private Endpoint.

Snapshots

Snapshots capture the full state of a running sandbox, including memory and disk. Use snapshots to:

• Suspend and resume: Pause a sandbox and restore it later with all processes and data intact.
• Clone environments: Create new sandboxes from a known-good state.
• Share baselines: Distribute preconfigured environments across your team.

Volumes

Volumes provide persistent storage that you can mount into sandboxes. You can use Microsoft-managed storage or bring your own Azure Blob container. Three volume types are available:

For more information, see Volumes.

Lifecycle states

Sandboxes go through the following states:

When the sandbox is stopped, the operation takes and preserves a snapshot based on the Suspend Mode (see the following section).

You can configure lifecycle policies for each sandbox:

• Auto-suspend: Suspend an idle sandbox after a configurable timeout. A sandbox becomes idle when it has no ingress (incoming) traffic, no code execution (via execute API), no interactive shell sessions, and no file operations.
• Suspend Mode: Choose between memory mode (full snapshot - disk + memory) or disk mode (preserve disk only).
• Auto-delete: Automatically delete sandboxes after a specified number of days after the sandbox is stopped.

Resource tiers

Each sandbox is assigned a resource tier that defines its CPU, memory, and disk allocation.

Sandboxes vs. dynamic sessions

For new projects, consider Azure Container Apps Sandboxes instead of dynamic sessions, especially when you need programmable control over isolated compute with persistent state. Sandboxes provide on-demand environments for AI agents, with hardware-level isolation, sub-second startup, and suspend and resume. When configured, rule-based egress policies help contain risky or unintended agent actions and limit access to your infrastructure and data.

Dynamic sessions offer a managed execution experience in which a session pool handles allocation and lifecycle. The following table compares the two options.

Related content

• Snapshots and state management for Sandboxes
• Egress policies and network controls for Sandboxes