Alternative and custom Sandbox images

AML’s own full and single-Agent images, Docker Hub tags, bleeding-edge GHCR channel, usage, and extension model are documented in AML Agent Sandbox images. Start there unless a third-party image or provider-native recipe is an explicit deployment requirement.

This page covers alternatives we have inspected and the compatibility checks required before replacing AML’s image. A public image containing the desired Agent is useful evidence, but it does not prove model credentials, network policy, Workspace transfer, entrypoint behavior, or production isolation.

Replacement image baseline

An alternative or custom image must provide the complete executable chain required by the selected Agent plus the tools required by its Sandbox provider:

• sh, mkdir, and rm for every image-backed provider;
• tar for Daytona and Modal Workspace transfer;
• the selected ACP Agent executable and its language/native runtime;
• a writable home and Workspace path for the configured user;
• project dependencies and every command launched by <Script /> or the Agent.

AML does not install missing packages when a Sandbox starts. Pin the alternative image by version or digest, then repeat the provider and Agent checks in the deployed identity and network environment before treating it as production-ready.

Alternative public images

OpenCode: Cloudflare Sandbox

Cloudflare publishes an official OpenCode variant on Docker Hub:

cloudflare/sandbox:0.12.5-opencode

For an immutable production input, the image inspected for this guide is:

cloudflare/sandbox@sha256:c34f783dcf456a135d8e5a1fdfd060001a133f304f9a3f556a4afac5f63a4c4a

AML verification on 2026-08-10 confirmed that the linux/amd64 image starts with an overridden shell entrypoint and contains sh, tar, mkdir, rm, Git, Node.js, and /usr/local/bin/opencode. The installed OpenCode version was 1.18.15, and opencode acp --help completed successfully.

This is a useful OpenCode-specific alternative when an application needs Cloudflare’s Sandbox server or base tooling. With AML’s Docker provider, the image proves executable-level compatibility only; it does not prove model credentials, network policy, project dependencies, Docker hardening, or a successful live model session.

import { AmlRuntime, dockerSandbox, localWorkspace, opencodeAgent } from "@aml-jsx/sdk"

const runtime = new AmlRuntime({
  agentProvider: opencodeAgent({
    env: {
      // Supply the model/provider credentials required by your OpenCode config.
    },
  }),
  sandboxProvider: dockerSandbox({
    image: "cloudflare/sandbox:0.12.5-opencode",
  }),
  workspaceProvider: localWorkspace({ directory: "/absolute/path/to/project" }),
})

AML’s Docker provider overrides the image entrypoint with its own keepalive shell and launches OpenCode later through docker exec. The image’s Cloudflare container server is therefore not used by this combination.

Sources: Cloudflare image variants and Docker Hub tags.

Cloudflare base variants

Cloudflare also publishes versioned base images:

Image	Included upstream	AML recommendation
cloudflare/sandbox:0.12.5	Ubuntu, Node.js 24, Bun, Git, curl, jq, and common utilities	Good public base for a custom Agent image; not Agent-ready by itself.
cloudflare/sandbox:0.12.5-python	Base image plus Python 3.11 and common data packages	Good for <Script /> and code-interpreter workloads; not Agent-ready by itself.
cloudflare/sandbox:0.12.5-musl	Minimal Alpine/musl environment	Use only after checking native binary and libc compatibility; not our default Agent base.

The base images use Node.js 24. AML itself requires Node.js 26 on the host application, but the container only needs the runtime required by the Agent and commands launched inside it. Do not assume the base image is suitable for running the AML application process itself.

Modal image recipes

Modal publishes official examples for OpenCode in a Modal Sandbox and Claude Code in a Modal Sandbox. These are image recipes, not public prebuilt Docker image names:

• the OpenCode example starts from modal.Image.debian_slim(), installs Git and gh, and runs OpenCode’s installer;
• the Claude Code example starts from modal.Image.debian_slim(), installs curl and Git, and runs Claude’s installer;
• Modal recommends building and publishing named Images separately when Sandbox startup is latency-sensitive.

AML’s current modalSandbox() adapter accepts a registry string and resolves it through Modal’s images.fromRegistry(). It does not accept an inline modal.Image definition or a Modal named Image. To use the official recipes with AML today:

1. translate the required installation steps into a linux/amd64 Dockerfile;
2. publish the resulting image to Docker Hub, GHCR, or another registry Modal can read;
3. verify its entrypoint compatibility and required shell utilities;
4. pass the immutable registry reference to modalSandbox({ image }).

import { modalSandbox } from "@aml-jsx/sdk"

const sandboxProvider = modalSandbox({
  image: "ghcr.io/your-organization/aml-opencode:2026-08-10",
  appName: "aml-production",
})

Modal documents support for loading existing public registry images. The image must be linux/amd64 and have a compatible entrypoint. AML additionally requires sh, tar, mkdir, and rm for Workspace hydration and reconciliation.

Claude Code is upstream guidance, not current AML support

AML does not currently ship a Claude Agent provider. Modal’s official Claude Code recipe is useful input for future image work, but an image alone does not create an AML provider or prove ACP compatibility.

Verify an image before recommending it

For repository development, build the current checkout and run its small image smoke check:

cd images/sandbox
npm run build
npm run check

For release or deployment evaluation, set AML_AGENT_SANDBOX_IMAGE to the exact Docker Hub semantic version or digest being validated. Do not treat latest or the GHCR dev channel as immutable inputs.

For another image, probe its required commands directly:

docker run --rm --entrypoint sh cloudflare/sandbox:0.12.5-opencode -lc '
  command -v sh
  command -v tar
  command -v git
  command -v opencode
  opencode acp --help
'

Then verify the complete stack:

1. the image architecture matches the Sandbox platform;
2. sh, transfer utilities, the ACP command, and its native Agent executable exist on PATH;
3. /workspace is readable and writable according to the requested access;
4. AML can create writable invocation state outside a read-only Workspace;
5. credentials arrive at runtime without entering image layers, prompts, or Workspace revisions;
6. the Agent can start one real session, use the requested model, and exit cleanly;
7. cancellation and output overflow reclaim the Agent process and disposable Sandbox;
8. image user, network, capabilities, resources, package provenance, and vulnerability policy match the deployment threat model.

Continue with Docker Sandbox, Modal Sandbox, and Agent/Sandbox compatibility for provider-specific behavior.