Docker isolation

Run untrusted plans without trusting the host shell. --docker spawns the agent (and reviewer) inside a container. The repo ships a docker/Dockerfile and entrypoint; --docker-image overrides the image name.

Quick start

# build the default image
docker build -t ralphterm:latest -f docker/Dockerfile .

# run a plan inside the container
ralphterm --docker --tasks-only docs/plans/feature.md

# use a custom image
ralphterm --docker --docker-image my-org/ralphterm:dev docs/plans/feature.md

Bind mounts

By default the container mounts:

• workspace (current repo) at /workspace read-write
• plan file at its resolved path read-write
• ~/.claude (or the configured agent auth dir) read-write
• ~/.config/ralphterm/ read-only
• ~/.config/ralphex/ read-only

Extra volumes and env vars

Pass through additional bind mounts and environment variables with the ralphex-compatible env variables:

# mount extra paths into the container
export RALPHEX_EXTRA_VOLUMES="/data/cache:/cache:ro,/tmp/scratch:/tmp/scratch"

# forward extra env vars
export RALPHEX_EXTRA_ENV="AWS_PROFILE,AWS_REGION,HTTP_PROXY"

ralphterm --docker docs/plans/feature.md

Also forwarded by default when set on the host: TZ, AWS_PROFILE, AWS_REGION. Use --preserve-anthropic-api-key to pass ANTHROPIC_API_KEY through.

Image build instructions

The Dockerfile is a small Debian-based image with git, the wrapper scripts under scripts/wrappers/, and the RalphTerm binary. Rebuild after changing wrappers:

docker build -t ralphterm:latest -f docker/Dockerfile .

# inspect what's inside
docker run --rm -it ralphterm:latest /bin/sh
ralphterm --version

Notes

• If the docker binary is missing, RalphTerm exits with a clear error before trying to start the run.
• Containers run with the calling user's UID/GID so files written into /workspace have correct ownership on the host.
• Use --docker-image with a content-addressed digest in CI to keep runs reproducible.