Images and resources

Settings on this page apply only to the Docker backend.

Sandbox image

The default image comes with Claude Code and Codex pre-installed. These are the only agents validated on this backend so far. The image is based on node:22-bookworm-slim and includes git, curl, gh, jq, python3 (with pip and venv), unzip, less, and procps. pip install works without a virtualenv.

The default Dockerfile ships inside the stashbase binary, and the image is built locally. The first Docker run offers to build it. Runs with --silent fail instead of prompting. To build it in advance:

stashbase agent docker build          # build the default image
stashbase agent docker build --force  # rebuild with the latest Claude Code and Codex

Update Claude Code and Codex

Claude Code and Codex don't update themselves inside the sandbox. To get the latest versions, rebuild the image:

stashbase agent docker build --force

This also picks up the latest base image. stashbase agent run reminds you when the default image is more than two weeks old, and stashbase agent docker doctor shows which versions it contains.

Custom images

To add tools the default image lacks, use your own image or Dockerfile:

[sandbox]
backend = "docker"
image = "myorg/my-agent-image:latest"   # pulled if missing locally
# or
# dockerfile = "./sandbox.Dockerfile"   # relative to the working directory; built and tagged locally

image and dockerfile are mutually exclusive. A custom image can add tools but can't loosen the sandbox. The capability drop and the firewall always apply, and the privileged firewall container always uses the built-in image.

A Dockerfile is rebuilt only when its tag is missing. After you edit it, remove the old image with docker image rm or run stashbase agent docker build --profile coding --force.

To override the image for one run (this also selects the Docker backend):

stashbase agent run --profile coding --docker-image node:22-alpine -- claude
stashbase agent run --profile coding --docker-dockerfile ./sandbox.Dockerfile -- claude

Resource limits

By default, containers have no CPU or memory cap. You can set one per profile:

[sandbox]
backend = "docker"
memory = "2g"
cpus = "1.5"

You can also set limits for a single run with --docker-memory and --docker-cpus. Unlike --docker-image, these flags don't select the Docker backend by themselves. agent validate checks that the values are in a format Docker accepts.