Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
Important
To manage and create sandboxes, you need the Azure role Container Apps SandboxGroup Data Owner. Assign this role to all users who create and manage sandboxes.
Sandboxes created during preview might not be compatible with future releases and might need to be recreated.
The API surface for Python SDK and Azure Container Apps CLI commands might change during preview.
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 are provisioned from prewarmed pools for near-instant availability.
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 public image 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.
| Scenario | Use sandboxes? | Why |
|---|---|---|
| AI code execution with state preservation | Yes | Suspend between tasks, resume with full context intact |
| Development environments | Yes | On-demand, suspendable environments that preserve state across sessions |
| Agent workflows | Yes | Give AI agents persistent, isolated workspaces across task boundaries |
| Interactive user sessions | Yes | Each user gets their own isolated compute environment |
| Secure multitenant compute | Yes | Strong isolation for running untrusted workloads from multiple tenants |
| Burst workloads | Yes | Scale from zero to thousands of sandboxes on demand |
| CI/CD pipelines | Yes | Ephemeral build and test environments that scale to zero when idle |
Choose the right Container Apps compute option
Use the following table to select the Container Apps compute type that fits your workload.
| Compute type | Best for | Lifecycle | State |
|---|---|---|---|
| Apps | Long-running services, APIs, web apps | Continuous | Stateless (external state stores) |
| Jobs | Run-to-completion tasks, batch processing | Start → run → complete | Stateless |
| Dynamic sessions | Managed code execution, LLM-generated scripts | Managed by session pool | Ephemeral |
| Sandboxes | Programmable isolated compute with lifecycle control | You manage: create, suspend, resume, delete | Stateful (snapshots, volumes) |
Key concepts
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 desired scope (Azure Subscription or Azure Resource Group) in the Azure portal or by using 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>"
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.
You can build disk images from:
- Public images: Prebuilt images available to all sandbox groups.
- Container registry images: Pull from public or private registries with optional authentication.
- Dockerfiles: Build custom images with a Dockerfile.
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
Microsoft manages volumes and provides persistent storage that you can mount into sandboxes. Two volume types are available:
| Volume type | Description |
|---|---|
| Azure Blob | Share data across multiple sandboxes (uploads and downloads, persistent artifacts). Mountable to multiple sandboxes at once. |
| Data Disk | High-performance volume for databases, build caches, and large working sets. Mountable to only one sandbox at a time. |
Lifecycle states
Sandboxes go through the following states:
| State | Description |
|---|---|
| Running | Actively executing, using CPU and memory |
| Stopped | Stopped by user, API, or Lifecycle policy |
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.
Architecture
Sandboxes use a two-plane architecture:
| Plane | Endpoint | Operations |
|---|---|---|
| ARM control plane | management.azure.com |
Create, update, delete, and list sandbox groups. Manage VNet connections. |
| ADC data plane | management.azuredevcompute.io |
Manage sandboxes, disk images, snapshots, files, volumes, secrets, ports, and egress policies. |
You create and manage sandbox groups through the ARM control plane. All operations on individual sandboxes and their resources go through the ADC data plane, scoped to a specific sandbox group.
Resource tiers
Each sandbox is assigned a resource tier that checks its CPU, memory, and disk allocation.
| Tier | CPU | Memory | Disk |
|---|---|---|---|
| XS | 0.25 cores | 0.5 GB | 20 GB |
| S | 0.5 cores | 1 GB | 20 GB |
| M (default) | 1 core | 2 GB | 20 GB |
| L | 2 cores | 4 GB | 40 GB |
| XL | 4 cores | 8 GB | 80 GB |
Considerations
Consider these points when working with sandboxes:
- Entra ID required: Only Microsoft Entra ID accounts can access sandboxes. Personal Microsoft accounts aren't supported.
- Networking controls: You can configure egress policies to control outbound traffic from sandboxes, including domain-based allow or deny rules, CIDR-based network rules, and VNet integration.
Sandboxes vs. dynamic sessions
Sandboxes and dynamic sessions both provide isolated compute environments in Container Apps, but they serve different needs.
| Dynamic sessions | Sandboxes | |
|---|---|---|
| Access pattern | HTTP request routing through a session pool management endpoint | Direct SDK and CLI control over individual sandboxes |
| State | Ephemeral, destroyed after cooldown | Stateful with suspend, resume, and snapshots |
| Developer control | Pool manages allocation and lifecycle | You manage sandbox lifecycle, files, ports, and policies |
| Image model | Code interpreter (built-in) or custom container | Disk images (OCI), snapshots, content packages |
| Persistent storage | Not available | Volumes (Azure Blob, Data Disk) |
| Networking | Basic isolation | Egress policies, VNet integration, port management |
| SDKs | REST API through pool endpoint | Coming soon: dedicated SDKs (C#, Python) |
Choose dynamic sessions when you need a managed execution experience that abstracts infrastructure. Choose Sandboxes when you need programmable control over isolated compute with state persistence.