Skip to main content
Guide

Disk images

A disk image defines the root filesystem a sandbox boots from. Start from a prebuilt public image, build a custom image from OCI, or commit a running sandbox to a new image.

You can create or use disk images in three ways:

Public imageCustom imageCommitted image
SourcePrebuilt and maintained by the platform.Built by you from a remote OCI container image.Built by you from a running sandbox's filesystem at commit time.
Best forGetting started, or when a stock base OS or runtime is all you need.Baking dependencies into an image you already publish to a registry.Capturing setup that's easier to do interactively inside a sandbox than to script.
Referenced byName, via --disk.ID, via --disk-id.ID, via --disk-id.

Discover public disk images​

Reference public disk images by simple name when you create a sandbox. To discover available public disk images:

  1. In the ACA Sandboxes portal, open your sandbox group.
  2. Select Disk images in the left menu.
  3. Select the Public tab.
  4. Review the image names. These public images appear in the Public Disk Image dropdown when you create a sandbox.
echo "==> Public disk images (valid --disk values):"
aca sandboxgroup disk list-public

Public images are provided as-is, and available versions can change without notice as new runtime versions become available.

NameSummaryDescription
ubuntuGeneral-purpose Linux sandboxUbuntu base with diagnostic tools, including htop, btop, dnsutils, and vim. Includes Buildah for in-sandbox Dockerfile builds, GitHub Copilot CLI, and GitHub CLI. Uses /bin/bash as the entrypoint.
nginxReady-to-serve web serverNGINX 1.25 with the same diagnostic tools as the Ubuntu image. Runs NGINX in the foreground.
copilotCopilot CLI agent sandboxBacks the GitHub Copilot preset. Uses systemd as PID 1 and includes GitHub Copilot CLI, GitHub CLI, Node.js 24, Python 3, and nodemon. A boot-time unit configures Git authentication. /AGENTS.md and skills are included.
claudeClaude Code agent sandboxUbuntu toolchain with a pinned Claude Code CLI version. A startup script configures Git authentication and reads ANTHROPIC_API_KEY at runtime.
azure-devFull Azure development environmentSystemd-based Ubuntu 26.04 environment with Azure CLI, Azure Developer CLI, Bicep, Azure Functions Core Tools, .NET 10, Node.js 24, Python and uv, Go, Java 17 and Maven, Docker, GitHub Copilot CLI, and Visual Studio Code CLI.
python-3.12-code-interpreterSandboxed code executionExposes a Model Context Protocol (MCP) endpoint for running untrusted Python code in isolation. This image's entrypoint starts Jupyter and the combined REST/MCP server on port 6000. See Using Python Code Interpreter.
python-3.11 to python-3.14Python runtimes (4)Python runtime images for versions 3.11, 3.12, 3.13, and 3.14.
node-22, node-24Node.js runtimes (2)Node.js runtime images for versions 22 and 24.
dotnet-8 to dotnet-10.NET runtimes (3).NET runtime images for versions 8, 9, and 10.
php-8.3, php-8.4PHP-FPM runtimes (2)PHP-FPM runtime images for versions 8.3 and 8.4.

Build a disk image from a container image​

Custom disk images are built from a remote OCI container image, so any dependencies baked into that image are available as soon as a sandbox boots. To build a custom disk image:

  1. In the ACA Sandboxes portal, open your sandbox group.
  2. Select Disk images.
  3. Select + Create.
  4. Optionally add identifying Labels for the image.
  5. Enter the Base Image URL. This remote OCI image is used to build your custom disk image. For example, docker.io/library/alpine:3.19.
  6. Configure authentication under Registry Authentication if the source registry is private. Choose No authentication, Username and token, or Managed identity.
  7. Select Create and wait for the image state to show Ready.
DISK_NAME="alpine-build-example-$RANDOM"

echo "==> Building custom disk image '$DISK_NAME' from alpine:3.19..."
aca sandboxgroup disk create --image docker.io/library/alpine:3.19 --name "$DISK_NAME"

List and inspect private disk images​

Disk images you create through a remote registry or by committing from a running sandbox are private and scoped to your sandbox group. To view private disk images:

  1. In the ACA Sandboxes portal, open your sandbox group.
  2. Select Disk images.
  3. Select the Private tab.
  4. Select a disk image row to open its details.
  5. Use filters or labels to find a specific image.
echo "==> Listing your private disk images:"
aca sandboxgroup disk list

echo "==> Get details for the first private disk image:"
DISK_IMAGE_ID=$(aca sandboxgroup disk list -o json | jq -r '.[0].id')
aca sandboxgroup disk get --id "$DISK_IMAGE_ID"

Boot a sandbox from a private disk image​

Sandboxes booted from custom or committed images use the disk image ID (--disk-id), not a name.

  1. In the ACA Sandboxes portal, open your sandbox group.
  2. Select Disk images.
  3. Open the Private tab.
  4. Select + from the disk image row under the Actions column.
  5. Confirm CPU, memory, labels, and environment settings.
  6. Select Create.
echo "==> Booting sandbox from disk-id $DISK_IMAGE_ID..."
aca sandbox create --disk-id "$DISK_IMAGE_ID"

Commit a running sandbox​

note

A sandbox is briefly paused while its filesystem is committed, then resumes after the disk image is created.

You can also create a disk image by committing the filesystem of a running sandbox. This captures runtime changes, such as package installs, downloads, and generated files, so any sandbox booted from the resulting image starts with that state already in place.

  1. In the ACA Sandboxes portal, open your sandbox group.
  2. Select Sandboxes.
  3. Select the running sandbox that you want to commit.
  4. In the upper-right corner, select the overflow menu (⋮).
  5. Select Commit Image from the dropdown.
  6. Select Commit to commit the sandbox to a new disk image.
PRIMER_LABEL="disks-commit-primer-$RANDOM"
echo "==> Booting primer sandbox (default disk)..."
aca sandbox create --disk-id "$DISK_IMAGE_ID" --label name="$PRIMER_LABEL"

echo "==> Looking up primer sandbox ID by label..."
SANDBOX_ID=$(aca sandbox list -l name="$PRIMER_LABEL" -o json | jq -r '.[0].id')

echo "==> Priming: write /example.txt..."
aca sandbox exec --id "$SANDBOX_ID" -c "echo 'hello world!' >> /example.txt"

COMMITTED_DISK_NAME="committed-disk-image-$RANDOM"
echo "==> Committing primer sandbox to disk image '$COMMITTED_DISK_NAME'..."
COMMITTED_DISK_ID=$(aca sandbox commit --id "$SANDBOX_ID" --name "$COMMITTED_DISK_NAME" -o json | jq -r '.diskImage.id')
echo "==> Committed disk image id: $COMMITTED_DISK_ID"

Using Python Code Interpreter​

When you create a sandbox from the code interpreter image, the MCP server runs automatically. The image's entrypoint starts Jupyter and the combined REST/MCP server on port 6000, so you don't need to install or start an MCP server yourself.

First, create the sandbox with a strong token:

$token = [Convert]::ToBase64String(
  [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
)

aca sandbox create `
  --group "<sandbox_group_name>" `
  --disk "python-3.12-code-interpreter" `
  --env MCP_AUTH_TOKEN=$token `
  --region "<Azure_region_name>" `
  -g "<resource_group_name>"

Then expose port 6000:

$base = (aca sandbox port add `
  --id "<SANDBOX_ID>" `
  --port 6000 `
  --anonymous `
  --group "<sandbox_group_name>" `
  --region "<Azure_region_name>" `
  -g "<resource_group_name>" `
  -o json | ConvertFrom-Json).url

The interpreter itself remains protected by Authorization: Bearer <MCP_AUTH_TOKEN>.

Next, test Python through the REST interface:

Invoke-RestMethod "$base/executions?identifier=test-1" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body (@{
    code = 'import sys; print("Python works"); print(sys.version)'
    timeoutInSeconds = 30
    executionType = "synchronous"
  } | ConvertTo-Json)

Finally, connect an MCP client using the URL stored in $base, with the /mcp path and bearer header. Replace <PORT_URL> with the value of $base:

{
  "servers": {
    "sandbox-code-interpreter": {
      "type": "http",
      "url": "<PORT_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}

The relevant article:

Delete a disk image​

A disk image can only be deleted after all dependent sandboxes and child (committed) disk images are deleted.

  1. In the ACA Sandboxes portal, open your sandbox group.
  2. Select Disk images.
  3. Select the Private tab.
  4. Locate the row for the disk image you want to delete, and select the bin under the Actions column.
  5. Confirm the deletion.
echo "==> Deleting the source sandbox..."
aca sandbox delete --id "$SANDBOX_ID" --yes

echo "==> Deleting the committed (child) disk image first..."
aca sandboxgroup disk delete --id "$COMMITTED_DISK_ID"

echo "==> Deleting the base disk image..."
aca sandboxgroup disk delete --id "$DISK_IMAGE_ID"

Create sandboxes

Boot from public and private disk images.

Learn more →

Snapshots

Capture a running sandbox and restore from it.

Learn more →

Volumes

Mount persistent storage into sandboxes.

Learn more →
Last updated on