Skip to content

docker.md

Latest commit

 

History

History
234 lines (168 loc) · 4.57 KB

docker.md

File metadata and controls

234 lines (168 loc) · 4.57 KB

Docker Sandboxing Guide

Why Docker?

Ralph runs agents with --dangerously-skip-permissions, which means the agent has full system access. Docker provides:

  1. Isolation: Agent can't affect your host system
  2. Resource limits: Prevent runaway CPU/memory usage
  3. Network control: Option to disable network access
  4. Reproducibility: Same environment everywhere

Recommendation: Always use ralph --docker for autonomous runs.

Quick Start

# Build the Docker image (first time only)
cd ~/.ralph-wiggum
docker compose -f docker/docker-compose.yml build

# Run Ralph in Docker
cd ~/my-project
ralph --docker plan
ralph --docker 20

How It Works

When you run ralph --docker, it:

  1. Mounts your project directory at /workspace
  2. Mounts git credentials (read-only)
  3. Passes through API keys from environment
  4. Runs the Ralph loop inside the container
  5. Commits and pushes from within the container

Configuration

Environment Variables

Set these in your host environment:

# Required: API keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."  # If using Codex

# Optional: Git identity
export GIT_AUTHOR_NAME="Your Name"
export GIT_AUTHOR_EMAIL="you@example.com"
export GIT_COMMITTER_NAME="Your Name"
export GIT_COMMITTER_EMAIL="you@example.com"

Resource Limits

Default limits in docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G

Adjust as needed for your workload:

# Run with custom limits
docker compose -f ~/.ralph-wiggum/docker/docker-compose.yml run --rm \
  --cpus=4 --memory=8g \
  ralph 20

Network Isolation

For maximum security, disable network access:

# In docker-compose.yml
services:
  ralph:
    network_mode: none

Warning: This prevents:

  • Package installation (npm install, pip install)
  • Git push/pull
  • API calls (agent won't work!)

Only use network isolation for post-implementation validation runs.

Mounting Additional Volumes

Private npm Registry

docker compose run --rm \
  -v ~/.npmrc:/home/ralph/.npmrc:ro \
  ralph 20

AWS Credentials

docker compose run --rm \
  -v ~/.aws:/home/ralph/.aws:ro \
  ralph 20

Custom CA Certificates

docker compose run --rm \
  -v /etc/ssl/certs:/etc/ssl/certs:ro \
  ralph 20

Building Custom Images

Extend the base Dockerfile for project-specific needs:

# Dockerfile.custom
FROM ralph-wiggum

# Install project-specific tools
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools

# Install specific Node version via nvm
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Pre-install common dependencies
RUN npm install -g typescript eslint prettier

Build and use:

docker build -f Dockerfile.custom -t ralph-custom .
docker run --rm -v $(pwd):/workspace ralph-custom 20

Debugging

View Container Logs

# Run with verbose output
RALPH_DEBUG=true ralph --docker plan

# Tail logs in another terminal
docker logs -f $(docker ps -q --filter ancestor=ralph-wiggum)

Interactive Shell

# Get a shell inside the container
docker compose -f ~/.ralph-wiggum/docker/docker-compose.yml run --rm \
  --entrypoint /bin/bash \
  ralph

Check Mounted Volumes

# Inside container
ls -la /workspace      # Project files
ls -la ~/.ssh          # SSH keys
cat ~/.gitconfig       # Git config

Troubleshooting

"Permission denied" on git push

SSH keys might not have correct permissions:

# Check key permissions on host
ls -la ~/.ssh/id_*

# Should be:
# -rw------- id_rsa (600)
# -rw-r--r-- id_rsa.pub (644)

"API key not found"

Environment variables aren't passed:

# Verify on host
echo $ANTHROPIC_API_KEY

# Explicit pass-through
docker compose run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ralph plan

Slow builds

Docker cache might be invalid:

# Rebuild with cache
docker compose -f docker/docker-compose.yml build

# Force fresh build
docker compose -f docker/docker-compose.yml build --no-cache

Out of disk space

Clean up Docker resources:

docker system prune -a
docker volume prune

Security Best Practices

  1. Never commit API keys: Use environment variables
  2. Use read-only mounts: :ro for credentials
  3. Limit resources: Prevent DoS from runaway processes
  4. Review commits: Don't auto-merge to main
  5. Rotate keys: Regularly rotate API keys used by Ralph
  6. Monitor usage: Track API costs and unusual patterns