Edit

Quickstart: Create your first serverless sandbox in Azure Container Instances (preview)

In this quickstart, you create a serverless sandbox in Azure Container Instances with the three sandbox APIs:

  • The AI agents group API (Azure Resource Manager REST), to create an AI agents group and connect to it.
  • The sandbox management API (REST), to create a sandbox in the group.
  • The sandbox gateway API (gRPC), to run a command, copy a file, and view logs in the sandbox.

Then you delete the resources.

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

Send the requests

The examples in this quickstart show the method, URL, headers, and body of each HTTP request. You can send them with any HTTP client. For example, in a Bash shell:

  • For the AI agents group API, use az rest, which authenticates to Azure Resource Manager with your Azure CLI sign-in. For example, this command sends the request that creates the AI agents group:

    subscriptionId=$(az account show --query id --output tsv)
    groupUrl="https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myAgentsGroup"
    apiVersion="api-version=2026-08-01-preview"
    
    az rest --method put --url "$groupUrl?$apiVersion" --body '{ "location": "centralus", "properties": {} }'
    
  • For the sandbox management API, save the endpoint and accessToken that the connect action returns, and use curl. For example, these commands connect to the group and send the request that creates a sandbox:

    { read -r endpoint; read -r accessToken; } < <(az rest --method post --url "$groupUrl/connect?$apiVersion" --query "[endpoint, accessToken]" --output tsv)
    
    curl -X PUT "$endpoint/sandboxes/sandbox1?$apiVersion" \
      -H "Authorization: Bearer $accessToken" -H "Content-Type: application/json" \
      -d '{ "location": "centralus", "properties": { "image": "mcr.microsoft.com/azurelinux/base/core:3.0", "resources": { "cpu": 1, "memory": 2 } } }'
    

Create an AI agents group

An AI agents group is an Azure Resource Manager resource of type Microsoft.ContainerInstance/AIAgentsGroups. It holds your sandboxes and the settings that they share. When you create an AI agents group, the service also creates a managed resource group in your subscription containing a storage account used to save and restore snapshots.

  1. Create a resource group:

    az group create --name myResourceGroup --location centralus
    
  2. Create the AI agents group:

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myAgentsGroup?api-version=2026-08-01-preview
    
    {
      "location": "centralus",
      "properties": {}
    }
    
  3. Creation of an AI agents group is a long-running operation. Check the group until properties.provisioningState is Succeeded:

    GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myAgentsGroup?api-version=2026-08-01-preview
    

Connect to the AI agents group

To manage sandboxes in the AI agents group, call the connect action of the group:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myAgentsGroup/connect?api-version=2026-08-01-preview

The response includes the group's sandbox management endpoint and a short-lived accessToken:

{
  "endpoint": "https://<group-endpoint-host>/subscriptions/{subscriptionId}/resourcegroups/myResourceGroup/providers/Microsoft.ContainerInstance/<group-path>",
  "accessToken": "<access-token>",
  "notAfter": "2026-11-04T10:30:00Z"
}

The endpoint value already includes the resource path for the group. Use the returned {endpoint} URL directly as the base URL for sandbox management requests (for example, {endpoint}/sandboxes/sandbox1), and pass {accessToken} in the Authorization: Bearer {accessToken} header. When the access token expires at the notAfter time, call connect again.

Create a sandbox

  1. Create a sandbox in the AI agents group:

    PUT {endpoint}/sandboxes/sandbox1?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",
        "guestOs": "linux",
        "architecture": "amd64",
        "resources": {
          "cpu": 1,
          "memory": 2
        }
      }
    }
    
  2. Sandbox creation is asynchronous. Get the sandbox until properties.provisioningState is Succeeded, which typically takes a few seconds:

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

    The response includes properties.connectionString, which contains the gateway address and bearer token for the sandbox:

    {
      "id": "/subscriptions/{subscriptionId}/resourcegroups/myResourceGroup/providers/Microsoft.ContainerInstance/<group-path>/sandboxes/sandbox1",
      "name": "<group-name>/sandbox1",
      "type": "Microsoft.ContainerInstance/sandboxes",
      "location": "centralus",
      "tags": {},
      "properties": {
        "resources": {
          "cpu": 1.0,
          "memory": 2.0,
          "disk": 0.0
        },
        "guestOs": "linux",
        "architecture": "amd64",
        "provisioningState": "Succeeded",
        "targetState": "Active",
        "connectionString": "address=<gateway-host>;token=<gateway-token>;token_type=bearer",
        "attachToAgentFabric": false
      }
    }
    

    Treat the connection string as a secret. Anyone with the token can run commands in the sandbox until the token expires.

  3. List the sandboxes in the group:

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

Connect to the sandbox gateway

After you create the sandbox, use a gRPC client to connect to the sandbox gateway (aci.sandboxgateway.SandboxGatewayService) and run operations inside the sandbox. Generate a gRPC client from sandboxgateway.proto and connect by using the values in properties.connectionString:

  • Connect to the gateway endpoint: Open a TLS gRPC connection to https://<gateway-host>:443 using the address from properties.connectionString.
  • Authenticate and route requests with the token: Pass authorization: Bearer <gateway-token> in the gRPC request headers (metadata). The gateway uses this token both to authorize the request and to identify the target sandbox.

To build the sample C# CLI tool (SandboxGatewayCli) used in the following steps, install the .NET 8 SDK and follow Build a C# CLI from sandboxgateway.proto.

Call aci.sandboxgateway.SandboxGatewayService/WaitForReady to wait until the guest inside the sandbox is running.

By using the sample C# CLI:

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

gRPC request payload:

{
  "timeoutSeconds": 120
}

Response:

{
  "ready": true,
  "currentState": "running"
}

Run a command in the sandbox

Call aci.sandboxgateway.SandboxGatewayService/ExecSandbox to run a command in the sandbox. command is the executable to run, and args are its arguments.

Use the sample C# CLI:

dotnet run -- -cs "address=<gateway-host>;token=<gateway-token>;token_type=bearer" exec /bin/sh -c "cat /etc/os-release; nproc"

gRPC request payload:

{
  "command": "/bin/sh",
  "args": ["-c", "cat /etc/os-release; nproc"],
  "timeoutSeconds": 60
}

The response includes stdout with the operating system of the image (Azure Linux 3.0) and the CPU count of the sandbox (1), stderr, and exitCode.

Copy a file into and out of the sandbox

  1. Write a file to the sandbox with aci.sandboxgateway.SandboxGatewayService/WriteFile (content is raw bytes, or Base64-encoded in JSON).

    By using the sample C# CLI:

    dotnet run -- -cs "address=<gateway-host>;token=<gateway-token>;token_type=bearer" write-file /tmp/hello.txt $'hello from my computer\n'
    

    gRPC request payload:

    {
      "path": "/tmp/hello.txt",
      "content": "aGVsbG8gZnJvbSBteSBjb21wdXRlcgo="
    }
    
  2. Append a line to the file inside the sandbox with aci.sandboxgateway.SandboxGatewayService/ExecSandbox.

    By using the sample C# CLI:

    dotnet run -- -cs "address=<gateway-host>;token=<gateway-token>;token_type=bearer" exec /bin/sh -c "echo 'hello from the sandbox' >> /tmp/hello.txt"
    

    gRPC request payload:

    {
      "command": "/bin/sh",
      "args": ["-c", "echo 'hello from the sandbox' >> /tmp/hello.txt"]
    }
    
  3. Read the file with aci.sandboxgateway.SandboxGatewayService/ReadFile.

    By using the sample C# CLI:

    dotnet run -- -cs "address=<gateway-host>;token=<gateway-token>;token_type=bearer" read-file /tmp/hello.txt
    

    gRPC request payload:

    {
      "path": "/tmp/hello.txt"
    }
    

    The streamed response returns the file bytes in content and "eof": true:

    hello from my computer
    hello from the sandbox
    

View sandbox logs

Fetch the sandbox logs with aci.sandboxgateway.SandboxGatewayService/GetLogs.

By using the sample C# CLI:

dotnet run -- -cs "address=<gateway-host>;token=<gateway-token>;token_type=bearer" logs 20

gRPC request payload:

{
  "tail": 20,
  "timestamps": true
}

For all the gateway methods, see Sandbox gateway API.

Clean up resources

  1. Delete the sandbox:

    DELETE {endpoint}/sandboxes/sandbox1?api-version=2026-08-01-preview
    Authorization: Bearer {accessToken}
    
  2. If you don't plan to do the tutorials, delete the AI agents group and the resource group. Deletion of an AI agents group is a long-running operation and deletes all sandboxes in the group.

    DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myAgentsGroup?api-version=2026-08-01-preview
    
    az group delete --name myResourceGroup
    

The tutorials use the AI agents group from this quickstart. To do them, keep the AI agents group.

Next steps