# Alternative and custom Sandbox images

Evaluate third-party images, custom image recipes, and compatibility requirements for AML Sandbox providers.
Canonical: https://agent-markup-language.com/docs/providers/sandboxes/images/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

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](https://agent-markup-language.com/docs/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:

```text
cloudflare/sandbox:0.12.5-opencode
```

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

```text
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.

```tsx
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](https://github.com/cloudflare/sandbox-sdk/blob/main/DOCKER_README.md) and [Docker Hub tags](https://hub.docker.com/r/cloudflare/sandbox/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](https://modal.com/docs/examples/opencode_server) and [Claude Code in a Modal Sandbox](https://modal.com/docs/examples/sandbox_agent). 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](https://modal.com/docs/guide/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 })`.

```ts
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](https://modal.com/docs/guide/existing-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.

**Note — 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:

```sh
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](https://agent-markup-language.com/docs/sandbox-images/#bleeding-edge-dev-image) as immutable inputs.

For another image, probe its required commands directly:

```bash
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](https://agent-markup-language.com/docs/providers/sandboxes/docker/), [Modal Sandbox](https://agent-markup-language.com/docs/providers/sandboxes/modal/), and [Agent/Sandbox compatibility](https://agent-markup-language.com/docs/compatibility/) for provider-specific behavior.