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.
A snapshot saves the state of a serverless sandbox in Azure Container Instances, including the processes that run in it and their memory. The service stores snapshots in the storage account it provisions in the managed resource group of your AI agents group. When you restore a sandbox from a snapshot, the sandbox starts from the moment of the snapshot and doesn't repeat the setup that you did in the source sandbox.
Use snapshots to prepare a sandbox once, for example with installed packages and a warmed-up agent, and then quickly start copies of it.
In this tutorial, you start a process in a sandbox that writes the time to a log every second. You snapshot the sandbox, and then restore copies of it. The logs in the copies show that they start from the state of the snapshot.
In this tutorial, you learn how to:
- Start a process in a source sandbox
- Save the sandbox in a snapshot with the
saveSnapshotaction - Restore a sandbox from the snapshot, and check its state
- Restore many sandboxes from the same snapshot
Prerequisites
An Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
The Azure CLI, version 2.60 or later, signed in with
az login, or another tool to send authenticated REST requests to Azure Resource Manager.The
Microsoft.ContainerInstanceresource provider registered in your subscription.az provider register --namespace Microsoft.ContainerInstance --waitThe Contributor, Azure Deployment Stack Owner, and Storage Blob Data Contributor roles assigned to the Compute Sandbox Groups service principal on your subscription, so that the service can provision the managed resource group and snapshot storage account in your subscription. To assign the roles, you need permission to create role assignments on the subscription, such as the Owner or User Access Administrator role:
subscriptionId=$(az account show --query id --output tsv) spObjectId=$(az ad sp show --id 1eeacc2b-ec4a-4b1e-977a-2b5fef2131c6 --query id --output tsv 2>/dev/null || \ az ad sp create --id 1eeacc2b-ec4a-4b1e-977a-2b5fef2131c6 --query id --output tsv) for role in "Contributor" "Azure Deployment Stack Owner" "Storage Blob Data Contributor"; do az role assignment create --assignee-object-id $spObjectId --assignee-principal-type ServicePrincipal \ --role "$role" --scope /subscriptions/$subscriptionId doneRole assignments can take up to 15 minutes to take effect.
Quota provisioned for serverless sandboxes in Azure Container Instances on your subscription:
Open New support request in the Azure portal (with Issue type set to Service and subscription limits (quotas) and Quota type set to Container Instances), select your subscription, and go to the Additional details tab.
Select Enter details to open the Quota details pane, choose your Location, select AIAgentsGroups - StandardCores (Preview) for Quota type, and fill in Networking type, Container Type, Total AIAgentsGroups Group Limit, and Total AIAgentsGroups Core Limit:
Submit the support request. After your quota request is approved, re-register the
Microsoft.ContainerInstanceresource provider (az provider register --namespace Microsoft.ContainerInstance --wait) so that your subscription picks up the newly enabled capabilities.
To connect to a running sandbox after you create an AI agents group and a sandbox (see Quickstart: Create your first serverless sandbox), a gRPC client generated from the sandbox gateway protobuf file,
sandboxgateway.proto. A gRPC client is required because the sandbox gateway exposes a gRPC service (aci.sandboxgateway.SandboxGatewayService) for in-sandbox operations such as waiting for readiness, running commands, transferring files, and reading logs. To use the cross-platform sample C# CLI in this documentation (supported on Linux, macOS, and Windows), install the .NET 8 SDK and build the CLI.Note
A gRPC client isn't required if you schedule and manage serverless sandboxes through Azure Kubernetes Service (AKS).
- An AI agents group, and the
{endpoint}and{accessToken}from theconnectaction. To create one, complete Quickstart: Create your first serverless sandbox.
Start a process in a source sandbox
Create the source sandbox:
PUT {endpoint}/sandboxes/source1?api-version=2026-08-01-preview Authorization: Bearer {accessToken} Content-Type: application/json { "location": "centralus", "properties": { "image": "mcr.microsoft.com/azurelinux/base/core:3.0", "resources": { "cpu": 1, "memory": 2 } } }Wait until
properties.provisioningStateisSucceeded. Then copyproperties.connectionStringfrom the response, and wait until the guest is ready (WaitForReady). Use the sample C# CLI:dotnet run -- -cs "<source1-connection-string>" waitIn
source1, start a background process that appends the current UTC time to/tmp/clock.logevery second (ExecSandbox):dotnet run -- -cs "<source1-connection-string>" exec /bin/sh -c "nohup sh -c 'while true; do date -u +%H:%M:%S >> /tmp/clock.log; sleep 1; done' >/dev/null 2>&1 < /dev/null &"Wait a few seconds, and then read
/tmp/clock.loginsource1:dotnet run -- -cs "<source1-connection-string>" exec cat /tmp/clock.logThe log has one line for each second since you started the process. For example:
10:15:01 10:15:02 10:15:03 10:15:04 10:15:05
Save the sandbox in a snapshot
Save a snapshot of the source sandbox by using the
saveSnapshotaction. When you save a snapshot, you pause the source sandbox and export its memory, filesystem, and runtime state. The snapshot name must be a valid DNS label (1-63 lowercase letters, digits, or hyphens, and it must start and end with a letter or digit).POST {endpoint}/sandboxes/source1/saveSnapshot?api-version=2026-08-01-preview Authorization: Bearer {accessToken} Content-Type: application/json { "snapshotName": "clock-snapshot" }The response includes an operation
endpointandaccessToken.{ "endpoint": "<operation-gateway-host>", "accessToken": "<operation-token>" }Call
aci.sandboxgateway.SandboxGatewayService/WaitForOperationCompleteon<operation-gateway-host>:443withauthorization: Bearer <operation-token>to wait until the snapshot export finishes. By using the sample C# CLI, pass the operationendpointandaccessTokenas a connection string:dotnet run -- -cs "address=<operation-gateway-host>;token=<operation-token>;token_type=bearer" wait-op 300gRPC request payload:
{ "timeoutSeconds": 300 }The response includes
"complete": trueand"terminalState": "succeeded". Note the time when the snapshot finishes.List the snapshots in the AI agents group.
GET {endpoint}/snapshots?api-version=2026-08-01-preview Authorization: Bearer {accessToken}The
valuearray in the response includesclock-snapshot.
Restore a sandbox from the snapshot
Wait at least 10 seconds, so that the current time moves past the time of the snapshot.
Create a sandbox from the snapshot. Set the
snapshotproperty instead ofimage:PUT {endpoint}/sandboxes/restored1?api-version=2026-08-01-preview Authorization: Bearer {accessToken} Content-Type: application/json { "location": "centralus", "properties": { "snapshot": "clock-snapshot" } }Wait until
properties.provisioningStateisSucceeded, copyproperties.connectionStringfrom the response, and wait until the guest is ready (WaitForReady).In
restored1, print the current UTC time and the contents of/tmp/clock.log:dotnet run -- -cs "<restored1-connection-string>" exec /bin/sh -c "date -u +%H:%M:%S; cat /tmp/clock.log"The log contains the timestamps from the source sandbox up to the moment of the snapshot, with a gap between the snapshot time and the time when the restored sandbox resumed. The restored sandbox started from the captured state of the snapshot rather than from a fresh image.
Restore many sandboxes from the same snapshot
You can create many sandboxes from the same snapshot in parallel by sending concurrent PUT requests with "snapshot": "clock-snapshot":
PUT {endpoint}/sandboxes/{sandboxName}?api-version=2026-08-01-preview
Authorization: Bearer {accessToken}
Content-Type: application/json
{
"location": "centralus",
"properties": {
"snapshot": "clock-snapshot"
}
}
Each copy starts from the same snapshot state, including any environment variables captured in the snapshot's memory, and then runs independently. When you restore a sandbox, don't specify image or environmentVariables with snapshot. You can set other properties, such as resources and an agent identity in agentIdentities.
Clean up resources
Delete the sandboxes that you created in this tutorial, including any sandboxes that you restored in parallel.
DELETE {endpoint}/sandboxes/source1?api-version=2026-08-01-preview Authorization: Bearer {accessToken}DELETE {endpoint}/sandboxes/restored1?api-version=2026-08-01-preview Authorization: Bearer {accessToken}DELETE {endpoint}/sandboxes/{sandboxName}?api-version=2026-08-01-preview Authorization: Bearer {accessToken}The snapshot stays in the AI agents group after you delete the source sandbox. If you no longer need it, delete it.
DELETE {endpoint}/snapshots/clock-snapshot?api-version=2026-08-01-preview Authorization: Bearer {accessToken}
If you don't plan to do the other tutorials, delete the AI agents group and the resource group.