Edit

Tutorial: Connect serverless sandboxes to a virtual network (preview)

You can connect an AI agents group for serverless sandboxes in Azure Container Instances (ACI) to a subnet in your Azure virtual network. Each sandbox in the group gets a private IP address from the subnet, so sandboxes can reach private resources in the virtual network, such as internal services, databases, and private endpoints.

In this tutorial, you deploy a web app with only a private IP address. You then create an AI agents group in the same virtual network, and reach the web app from a sandbox.

In this tutorial, you learn how to:

  • Create a virtual network with a delegated subnet for sandboxes
  • Deploy a private web app in the virtual network
  • Create an AI agents group that's connected to the subnet
  • Reach the private web app from a sandbox

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

Create a virtual network

Create a virtual network with two subnets:

Subnet Delegation Used by
sandbox-subnet Microsoft.ContainerInstance/AIAgentsGroups The sandboxes. Each sandbox uses one IP address.
app-subnet Microsoft.ContainerInstance/containerGroups The private web app in this tutorial.
az group create --name myResourceGroup --location centralus

az network vnet create --resource-group myResourceGroup --name myVnet --location centralus --address-prefix 10.10.0.0/16

az network vnet subnet create --resource-group myResourceGroup --vnet-name myVnet --name sandbox-subnet \
  --address-prefixes 10.10.0.0/21 --delegations Microsoft.ContainerInstance/AIAgentsGroups

az network vnet subnet create --resource-group myResourceGroup --vnet-name myVnet --name app-subnet \
  --address-prefixes 10.10.8.0/24 --delegations Microsoft.ContainerInstance/containerGroups

Size the sandbox subnet for the number of sandboxes that you plan to run at the same time. Each sandbox uses one IP address from the subnet. The /21 subnet in this example has room for about 2,000 sandboxes.

Important

For outbound internet access (egress), associate a NAT gateway with the sandbox subnet in your virtual network and set the subnet's default outbound access setting (defaultOutboundAccess) to true. For NAT gateway configuration guidance, see Configure container group egress with a NAT gateway.

Deploy a private web app

Deploy a container group in app-subnet. The container group has only a private IP address, so it isn't reachable from the internet:

az container create --resource-group myResourceGroup --name private-web \
  --image mcr.microsoft.com/azuredocs/aci-helloworld --vnet myVnet --subnet app-subnet --os-type Linux --cpu 1 --memory 1.5

az container show --resource-group myResourceGroup --name private-web --query ipAddress.ip -o tsv

The output is a private IP address from app-subnet, such as 10.10.8.4.

Create an AI agents group in the virtual network

  1. Create the AI agents group with the resource ID of sandbox-subnet in properties.networkProfile.subnets:

    PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myVnetAgentsGroup?api-version=2026-08-01-preview
    
    {
      "location": "centralus",
      "properties": {
        "networkProfile": {
          "subnets": [
            {
              "id": "/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/sandbox-subnet"
            }
          ]
        }
      }
    }
    
  2. Check the AI agents group until properties.provisioningState is Succeeded, and then call connect to get its {endpoint} and {accessToken}:

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

All the sandboxes in the group use the subnet. You can't change the network profile of an AI agents group after you create it.

Reach the private web app from a sandbox

  1. Create a sandbox in the group. The azure-cli image includes curl:

    PUT {endpoint}/sandboxes/vnet1?api-version=2026-08-01-preview
    Authorization: Bearer {accessToken}
    Content-Type: application/json
    
    {
      "location": "centralus",
      "properties": {
        "image": "mcr.microsoft.com/azure-cli"
      }
    }
    

    Wait until properties.provisioningState is Succeeded. Then copy properties.connectionString from the response, and wait until the guest is ready (WaitForReady). By using the sample C# CLI:

    dotnet run -- -cs "<vnet1-connection-string>" wait
    
  2. In vnet1, request the private web app (ExecSandbox). Replace <private-web-ip> with the private IP address of private-web:

    dotnet run -- -cs "<vnet1-connection-string>" exec curl -s http://<private-web-ip>
    

    The response contains the HTML of the web app, which includes this text:

    Welcome to Azure Container Instances!
    

The sandbox reached the web app through the virtual network. A sandbox in an AI agents group that isn't connected to the virtual network can't reach this private IP address.

Note

For ACI serverless sandboxes connected to a virtual network, network isolation depends on the delegated subnet. To block or restrict traffic in any direction (inbound or outbound), configure a network security group (NSG) on the sandbox subnet.

Clean up resources

  1. Delete the AI agents group. Deleting an AI agents group is a long-running operation. It also deletes the sandboxes in the group:

    DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myVnetAgentsGroup?api-version=2026-08-01-preview
    
  2. Delete the web app and the virtual network. Delete the virtual network after the AI agents group deletion finishes. You can't delete a subnet while an AI agents group uses it.

    az container delete --resource-group myResourceGroup --name private-web --yes
    az network vnet delete --resource-group myResourceGroup --name myVnet
    

Next steps