Use aspire deploy to deploy Aspire applications to Azure Container Apps Sandboxes. Aspire provisions a sandbox group, an Azure Container Registry, and the managed identities and role assignments the group needs. It then builds or resolves a container image for each compute resource and runs it as a sandbox with the lifecycle and endpoint settings you configure in your AppHost.
Start with Deploy to Azure for the shared Azure
deployment model, authentication, and target selection.
Add Azure Container Apps Sandboxes support to your AppHost:
Aspire CLI — Add Azure Container Apps Sandboxes
aspireaddAspire.Hosting.Azure.Sandboxes
The Aspire CLI adds the 📦 Aspire.Hosting.Azure.Sandboxes integration to your AppHost. The package is prerelease-only while the Azure service is in preview.
Then add a sandbox group to your AppHost. When the sandbox group is the only compute environment in the AppHost, Aspire automatically deploys container-backed compute resources—projects, containers, and Dockerfile-based resources—to it:
The sandbox group only affects publish and deploy. When you run the AppHost locally with aspire run, Aspire adds the sandbox group to the app model but doesn’t provision Azure sandbox resources, so your resources run locally as usual.
For a standard deployment, you only need the sandbox group and your compute resources. Use PublishAsAzureSandbox only when you want to customize the sandbox runtime options for a resource.
Use the lifecycle options to suspend idle sandboxes or delete them after an interval. When you don’t set AutoSuspendEnabled or AutoDeleteEnabled, Aspire doesn’t send a lifecycle policy for that setting, and the service defaults apply.
Option
Description
AutoSuspendEnabled
Enables or disables auto-suspend. Required when you set AutoSuspendInterval or AutoSuspendMode.
AutoSuspendInterval
How long a sandbox can be idle before it’s suspended.
AutoSuspendMode
What the sandbox preserves when it’s suspended: Memory preserves memory and disk state, Disk preserves disk state only, and None disables snapshot preservation.
AutoDeleteEnabled
Enables or disables auto-delete. Required when you set AutoDeleteInterval or AutoDeleteTrigger.
AutoDeleteInterval
How long to wait before the sandbox is deleted.
AutoDeleteTrigger
The event that starts the auto-delete interval: AfterSuspend or AfterCreation.
Durations must use whole-second precision. C# AppHosts use TimeSpan values, and TypeScript AppHosts use numbers of milliseconds, where one second is 1_000.
Aspire creates sandbox ports only for endpoints that are marked external, such as with WithExternalHttpEndpoints. Each exposed port gets a public HTTPS URL on the sandbox proxy, which terminates TLS and forwards traffic to the container’s target port.
Authenticated by default. External endpoints require Microsoft Entra ID authentication by default. The sandbox port doesn’t use an allow-list, so any authenticated Entra ID user can access it.
Anonymous access is opt-in. To allow anonymous access, set Anonymous to true for the endpoint in AzureSandboxOptions.Endpoints, as shown in the preceding example.
HTTP only. Sandbox ports support HTTP and HTTP/2 endpoints. TCP endpoints aren’t supported.
Target ports are required. Each external endpoint needs a target port. Endpoints that share a target port share one sandbox port, so they must use the same protocol and anonymous-access policy.
.NET projects. When an external project resource has the usual paired HTTP and HTTPS endpoints on the same target port, Aspire exposes one sandbox port that forwards HTTP to the container on that shared target port (8080 when no target port is configured). References to either endpoint resolve to the same HTTPS URL. An external HTTPS endpoint without a matching HTTP endpoint on the same target port isn’t supported.
Public URLs for each exposed endpoint, along with a link to each sandbox group’s dashboard, appear in the deployment summary after aspire deploy completes.
A sandbox can reference another sandbox’s endpoint when both resources are deployed to the same sandbox group and the referenced endpoint is external. The reference resolves to the referenced sandbox’s public HTTPS URL, so Aspire deploys the referenced sandbox first. Private service discovery and references across sandbox groups aren’t supported.
Sandbox egress uses full traffic inspection with a deny-by-default policy. Aspire allows outbound traffic only to hosts that it finds in the resolved environment variables and arguments for each sandbox, such as endpoint URLs and the address fields of connection strings from referenced resources.
When an AppHost contains more than one compute environment, assign each compute resource explicitly with WithComputeEnvironment. PublishAsAzureSandbox uses that assignment and doesn’t select an environment on its own:
After Azure provisions the sandbox group, Aspire creates disk images, sandboxes, lifecycle settings, and ports through the Azure Container Apps Sandboxes data-plane API. Those calls run as the identity that runs aspire deploy, so Aspire grants that identity the built-in Container Apps SandboxGroup Data Owner role, scoped to the sandbox group it provisions.
When you run aspire deploy directly, Aspire binds the role assignment to the authenticated Azure credential’s object ID and principal type. When you deploy the Bicep generated by aspire publish yourself, supply the userPrincipalId and principalType parameters for the identity that performs the deployment.
For a new sandbox group, Aspire creates a dedicated user-assigned managed identity, attaches it to the sandbox group, and grants it only the AcrPull role on the group’s Azure Container Registry. The service uses this identity to import private images from the registry. Public registry images are imported without it, and registry credentials aren’t sent to the service or stored in deployment state.
Use WithAcrPullIdentity to supply a different user-assigned identity. For sandbox groups that Aspire creates, the identity is attached automatically, but you’re responsible for granting it AcrPull on the registry.
To deploy into a sandbox group that already exists, mark it as existing. Aspire doesn’t create role assignments or an image pull identity for an existing sandbox group, so before you deploy:
Grant the deployment identity the Container Apps SandboxGroup Data Owner role on the sandbox group.
Attach a user-assigned managed identity to the sandbox group, grant it AcrPull on the registry that the group uses, and pass it to WithAcrPullIdentity. The identity must also be marked as existing; otherwise, publish and deploy fail.
The following example references an existing sandbox group, container registry, and image pull identity:
var builder =DistributedApplication.CreateBuilder(args);
var resourceGroup =builder.AddParameter("sandboxResourceGroup");
var groupName =builder.AddParameter("sandboxGroupName");
var registryName =builder.AddParameter("sandboxRegistryName");
var pullIdentityName =builder.AddParameter("sandboxPullIdentityName");
var registry =builder.AddAzureContainerRegistry("registry")
.AsExisting(registryName,resourceGroup);
var pullIdentity =builder.AddAzureUserAssignedIdentity("sandbox-pull")
.AsExisting(pullIdentityName,resourceGroup);
builder.AddAzureSandboxGroup("sandboxes")
.AsExisting(groupName,resourceGroup)
.WithAzureContainerRegistry(registry)
.WithAcrPullIdentity(pullIdentity);
builder.Build().Run();
Aspire uses the subscription, resource group, location, and name from the existing sandbox group’s Azure outputs rather than the resource group of the current deployment.
Sandbox groups are Azure Resource Manager resources, but sandboxes, disk images, ports, and lifecycle settings are exposed only through the regional data-plane API. Aspire therefore provisions the sandbox group with Bicep and performs the sandbox deployment itself.
aspire publish generates Bicep for the sandbox group, container registry, managed identities, and role assignments. Sandboxes, disk images, ports, and their URLs are created at deploy time, so they aren’t part of the published output.
aspire deploy provisions the Azure resources, builds or resolves each workload image to an immutable Linux/amd64 digest, creates the disk image and sandbox, configures lifecycle settings and ports, and records the results in deployment state.
aspire destroy removes the current and retained sandboxes and disk images before Azure resource cleanup.
Aspire labels the sandboxes and disk images it creates with the AppHost and Azure deployment scope. Those labels let a later deploy or destroy find the resources even after you clear deployment state with --clear-cache, without affecting resources that belong to other apps.
To keep endpoint references working during an ordinary redeploy of the same image and endpoint policy, Aspire can retain the immediately previous sandbox until the next successful deployment. When the image digest, endpoint exposure, protocol, or anonymous-access setting changes, Aspire removes the previous sandbox immediately so an older workload or security configuration doesn’t stay reachable. If Aspire can’t remove it after such a change, the deployment reports a failure but keeps the new deployment and its state.
Aspire