AML Agent Sandbox images

AML publishes ready-to-use container images for running Agents and AML workflows with Docker, Daytona, and Modal. The default full image contains every built-in Agent. Smaller stable variants contain one Agent while preserving the same AML and system runtime.

Stable images on Docker HubBrowse versioned releases and moving full or Agent-specific tags.

Bleeding edge on GHCRInspect the mutable, full dev image built from main.

Image changelogReview changes released independently from the AML SDK and CLI.

What every variant contains

Every image variant is built from the same images/sandbox/Dockerfile and includes:

• the aml CLI and @aml-jsx/sdk, installed outside /workspace so clean mounted workflows can import the SDK;
• Node.js 26 and npm;
• Python 3, pip, and venv;
• Git, OpenSSH, curl, CA certificates, jq, ripgrep, patch, Bash, and common shell/archive utilities;
• a Debian Bookworm/glibc runtime and the non-root aml user with writable home, /tmp, and /workspace.

The images deliberately exclude credentials, Agent login state, project dependencies, browsers, cloud CLIs, Docker-in-Docker, compilers, and broad language toolchains. Add project-specific software in a derived image instead of reinstalling it whenever a Sandbox starts.

Choose a variant

Single-Agent variants are clean builds. They select their Agent dependencies before npm install; they do not inherit full and delete other Agents in a later layer. This makes the published image smaller both on disk and over the network.

Variant	Use it when	Agent packages and commands	Stable tags	Docker Hub
Full	The application may choose different Agents at runtime, or you want the most convenient development image.	Every Agent listed below.	X.Y.Z, X.Y.Z-full, latest, full	Full tags
Codex	Every workflow uses codexAgent().	codex-acp 1.4.0 and codex 0.147.0.	X.Y.Z-codex, codex	Codex tags
Copilot	Every workflow uses copilotAgent().	copilot 1.0.80.	X.Y.Z-copilot, copilot	Copilot tags
GLM	Every workflow uses glmAgent().	glm-acp-agent 1.5.0.	X.Y.Z-glm, glm	GLM tags
OpenCode	Every workflow uses opencodeAgent().	opencode 1.18.18.	X.Y.Z-opencode, opencode	OpenCode tags
Pi	Every workflow uses piAgent().	pi 0.84.2, pi-acp 0.0.33, and pi-mcp-adapter 2.26.0.	X.Y.Z-pi, pi	Pi tags

The versions above describe the current repository build. The image package manifest is the source of truth when a dependency changes.

Choose full when the Agent is selected dynamically. Choose a single-Agent variant when the application always uses one Agent and image size matters.

The image does not select the Agent

opencodeAgent() selects OpenCode; the image only supplies its executable and runtime. Pairing codexAgent() with an OpenCode-only image fails because codex-acp and codex are deliberately absent.

Understand the stable tags

Docker Hub is the canonical stable registry.

• X.Y.Z and X.Y.Z-full identify the same full release.
• X.Y.Z-<agent> identifies the matching single-Agent release.
• latest and full move to the newest validated full release.
• codex, copilot, glm, opencode, and pi move to the newest validated release in that Agent lane.

AML’s release process treats versioned tags as immutable. It builds and publishes every versioned variant first, runs the matching real Agent smoke against each pushed digest, signs the digests, and only then advances the moving tags. Stable releases also include SBOM and provenance attestations.

Use a versioned tag while evaluating a release, and pin its digest when the exact registry artifact must never change:

Pin a stable digest

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

const sandbox = dockerSandbox({
  image: "wearesingular/aml-agent-sandbox@sha256:IMAGE_DIGEST",
})

Bleeding-edge dev image

ghcr.io/we-are-singular/aml-agent-sandbox:dev is the public bleeding-edge image built from relevant changes on main.

Pull the bleeding-edge image

docker pull ghcr.io/we-are-singular/aml-agent-sandbox:dev

The dev image intentionally remains full and non-versioned. It is not reduced to a single-Agent dependency set: Codex, Copilot, GLM, OpenCode, and Pi are all present. Normal image cleanup still applies, but there are no dev-codex, dev-opencode, or other GHCR variant lanes.

The development image workflow explicitly builds IMAGE_VARIANT=full, runs its deterministic image check and dependency audit, and replaces the mutable dev tag. AML’s repository smoke matrix uses this channel so changes can be exercised before a stable Docker Hub release.

Do not treat dev as a production pin

dev can change after any relevant merge to main, has no semantic version, and is not a stable mirror of Docker Hub. Use it for unreleased integration testing. Use a Docker Hub version or digest for reproducible deployments.

Pull and inspect an image

Pull the full stable image when you want every Agent:

docker pull wearesingular/aml-agent-sandbox:latest

Pull a versioned single-Agent image when the Agent is fixed:

docker pull wearesingular/aml-agent-sandbox:X.Y.Z-opencode
docker run --rm wearesingular/aml-agent-sandbox:X.Y.Z-opencode opencode --version

Replace X.Y.Z with a tag listed on Docker Hub. You can also inspect the shared runtime directly:

docker run --rm wearesingular/aml-agent-sandbox:X.Y.Z-opencode sh -lc '
  node --version
  npm --version
  python --version
  pip --version
  jq --version
'

Configure the image in AML

Docker, Daytona, and Modal use the full wearesingular/aml-agent-sandbox:latest image when their factory receives no image or Daytona snapshot override:

Use the default full image

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

const sandbox = dockerSandbox()

To use a single-Agent image, configure the matching Agent and Sandbox providers together:

Use the OpenCode variant

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

const runtime = new AmlRuntime({
  agentProvider: opencodeAgent({
    env: { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
  }),
  sandboxProvider: dockerSandbox({
    image: "wearesingular/aml-agent-sandbox:X.Y.Z-opencode",
  }),
})

The same image reference belongs on daytonaSandbox({ image }) or modalSandbox({ image }) when those platforms can pull it. Image identity belongs to the provider factory, not an <Sandbox image="…" /> prop.

Extend a variant

Start from the smallest variant that contains the selected Agent, then add only the project tools the workflow needs. This example adds the SQLite CLI to OpenCode:

Dockerfile

FROM wearesingular/aml-agent-sandbox:X.Y.Z-opencode

USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends sqlite3 \
    && rm -rf /var/lib/apt/lists/*

USER aml
WORKDIR /workspace

Build the derived image and pass it to AML:

docker build --tag example/aml-opencode:1 .

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

const sandbox = dockerSandbox({
  image: "example/aml-opencode:1",
})

Pin the FROM reference before publishing the derived image. Build tools are not part of the shared runtime; add them only when a dependency requires compilation, and use a separate build stage when they do not belong in the final image. Keep model, repository, and registry credentials out of image layers.

Image and Sandbox responsibilities

The image supplies software

Operating-system files, Agent executables, interpreters, package managers, and command-line tools.

The provider supplies execution

Container or remote-environment creation, Workspace attachment, process transport, cancellation, and cleanup.

The application supplies policy

Credentials, network access, resource limits, project dependencies, image pinning, and deployment hardening.

An image is not a complete isolation policy. Validate the selected Agent, credentials, network policy, Workspace behavior, provider limits, and container hardening together before production use.

Continue with Run AML in a Sandbox image for a runnable Docker walkthrough, alternative and custom images for third-party recipes and verification guidance, and production security for the deployment boundary.