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, e.g. after a CLI update

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.