ralph-claude-code/docs/user-guide/04-docker-setup.md

Docker Setup (Windows & Cross-Platform)

Ralph runs natively on Linux and macOS. For Windows users (or anyone who prefers containerized execution), Ralph can run inside a Docker container with full functionality.

Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• Windows users: Docker Desktop must use the WSL 2 backend (default on modern installations)
• Docker Desktop must be running before executing any docker commands. Look for the Docker whale icon in your system tray (Windows) or menu bar (macOS).
• Your ANTHROPIC_API_KEY

Quick Start

1. Build the image

From the Ralph repository root:

docker build -t ralph-claude-code .

2. Run Ralph in your project

cd /path/to/your-project

docker run -it --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd):/workspace" \
  ralph-claude-code \
  ralph --monitor

Windows PowerShell:

cd C:\path\to\your-project

docker run -it --rm `
  -e ANTHROPIC_API_KEY="$env:ANTHROPIC_API_KEY" `
  -v "${PWD}:/workspace" `
  ralph-claude-code `
  ralph --monitor

Using Docker Compose

The repository includes a docker-compose.yml for convenience:

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Run Ralph
docker compose run --rm ralph ralph --monitor

To customize, edit docker-compose.yml. Uncomment the volume mounts for git config and SSH keys if you need git push from inside the container:

volumes:
  - ./:/workspace
  - ~/.gitconfig:/home/ralph/.gitconfig:ro
  - ~/.ssh:/home/ralph/.ssh:ro

Convenience Wrapper Scripts

The docker/ directory contains wrapper scripts that handle volume mounts, UID mapping, and API key forwarding automatically:

Linux/macOS/WSL:

./docker/ralph-docker --monitor
./docker/ralph-docker --live --verbose

Windows PowerShell:

.\docker\ralph-docker.ps1 --monitor
.\docker\ralph-docker.ps1 --live --verbose

File Permissions (UID/GID Mapping)

When Docker mounts your project directory, files created inside the container need to have the correct ownership on the host. The container supports RALPH_UID and RALPH_GID environment variables:

docker run -it --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e RALPH_UID="$(id -u)" \
  -e RALPH_GID="$(id -g)" \
  -v "$(pwd):/workspace" \
  ralph-claude-code \
  ralph --monitor

The wrapper scripts (docker/ralph-docker) set these automatically.

Git Integration

To enable git commits and pushes from inside the container, mount your git configuration:

docker run -it --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd):/workspace" \
  -v "$HOME/.gitconfig:/home/ralph/.gitconfig:ro" \
  -v "$HOME/.ssh:/home/ralph/.ssh:ro" \
  ralph-claude-code \
  ralph --monitor

Running Tests Inside Docker

# Run all tests
docker run --rm ralph-claude-code bash -c 'cd /opt/ralph-claude-code && npm test'

# Run specific test suite
docker run --rm ralph-claude-code bash -c 'cd /opt/ralph-claude-code && npm run test:unit'

Windows-Specific Notes

Line Endings

The repository includes a .gitattributes file that forces LF line endings for all shell scripts. This prevents Windows' CRLF line endings from corrupting bash scripts. If you clone the repository on Windows, this is handled automatically.

If you encounter \r errors when running scripts, ensure .gitattributes is respected:

git config core.autocrlf input
git rm --cached -r .
git reset --hard

Volume Mount Performance

For best performance on Windows, store your projects in the WSL 2 filesystem rather than the Windows filesystem:

# Faster (WSL filesystem)
\\wsl$\Ubuntu\home\user\my-project

# Slower (Windows filesystem mounted in WSL)
/mnt/c/Users/user/my-project

PowerShell Environment Variables

# Set API key for current session
$env:ANTHROPIC_API_KEY = "sk-ant-..."

# Or persist across sessions
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")

Troubleshooting

"error during connect: docker daemon is not running"

Docker Desktop is not started. On Windows, launch Docker Desktop from the Start menu and wait until the whale icon in the system tray shows "Docker Desktop is running". On macOS, launch it from Applications. On Linux, start the daemon with sudo systemctl start docker.

"ANTHROPIC_API_KEY is not set"

The container warns if no API key is provided. Pass it with -e ANTHROPIC_API_KEY=....

Permission denied on mounted files

Set RALPH_UID and RALPH_GID to match your host user (see File Permissions section above).

tmux not working

Ensure you run the container with -it flags (interactive + TTY). Without TTY, tmux cannot create sessions. Use ralph without --monitor in non-interactive environments.

Container can't access the network

Docker Desktop may need network access enabled. Check Docker Desktop settings and firewall rules.

What's in the Container

The Docker image includes all Ralph dependencies:

Component	Version
Debian	bookworm-slim
Bash	5.2+
Node.js	20 LTS
jq	Latest
Git	Latest
tmux	Latest
GNU coreutils	Latest
Claude Code CLI	Latest