Edit

Tutorial: Save and restore a serverless sandbox (preview)

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 saveSnapshot action
  • 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.ContainerInstance resource provider registered in your subscription.

    az provider register --namespace Microsoft.ContainerInstance --wait
    
  • The 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
    done
    

    Role assignments can take up to 15 minutes to take effect.

  • Quota provisioned for serverless sandboxes in Azure Container Instances on your subscription:

    1. 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.

    2. 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:

      Screenshot of the New support request page in the Azure portal showing the Quota details pane with AIAgentsGroups - StandardCores (Preview) selected.

    3. Submit the support request. After your quota request is approved, re-register the Microsoft.ContainerInstance resource 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).

Start a process in a source sandbox

  1. 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.provisioningState is Succeeded. Then copy properties.connectionString from the response, and wait until the guest is ready (WaitForReady). Use the sample C# CLI:

    dotnet run -- -cs "<source1-connection-string>" wait
    
  2. In source1, start a background process that appends the current UTC time to /tmp/clock.log every 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 &"
    
  3. Wait a few seconds, and then read /tmp/clock.log in source1:

    dotnet run -- -cs "<source1-connection-string>" exec cat /tmp/clock.log
    

    The 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

  1. Save a snapshot of the source sandbox by using the saveSnapshot action. 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 endpoint and accessToken.

    {
      "endpoint": "<operation-gateway-host>",
      "accessToken": "<operation-token>"
    }
    
  2. Call aci.sandboxgateway.SandboxGatewayService/WaitForOperationComplete on <operation-gateway-host>:443 with authorization: Bearer <operation-token> to wait until the snapshot export finishes. By using the sample C# CLI, pass the operation endpoint and accessToken as a connection string:

    dotnet run -- -cs "address=<operation-gateway-host>;token=<operation-token>;token_type=bearer" wait-op 300
    

    gRPC request payload:

    {
      "timeoutSeconds": 300
    }
    

    The response includes "complete": true and "terminalState": "succeeded". Note the time when the snapshot finishes.

  3. List the snapshots in the AI agents group.

    GET {endpoint}/snapshots?api-version=2026-08-01-preview
    Authorization: Bearer {accessToken}
    

    The value array in the response includes clock-snapshot.

Restore a sandbox from the snapshot

  1. Wait at least 10 seconds, so that the current time moves past the time of the snapshot.

  2. Create a sandbox from the snapshot. Set the snapshot property instead of image:

    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.provisioningState is Succeeded, copy properties.connectionString from the response, and wait until the guest is ready (WaitForReady).

  3. 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

  1. 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}
    
  2. 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.

Next steps