Running Claude Code in Containers

Table of content

Why Containers?

Running Claude Code directly on your machine works fine for quick tasks. But containers unlock capabilities you can’t get locally:

Isolation - Agent mistakes stay contained. A rogue rm -rf won’t touch your actual files.
Scalability - Spin up parallel agents across multiple repositories simultaneously.
24/7 operation - Run agents on cloud servers while you sleep.
Consistency - Same environment everywhere. No “works on my machine” problems.
Security - Limit network access, filesystem permissions, and resource usage.

Docker Setup

Basic Dockerfile

FROM node:20-slim

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Create non-root user
RUN useradd -m -s /bin/bash agent
USER agent
WORKDIR /home/agent/workspace

# Set API key at runtime, not build time
ENV ANTHROPIC_API_KEY=""

ENTRYPOINT ["claude"]

Build it:

docker build -t claude-agent .

Running the Container

Interactive mode:

docker run -it \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/home/agent/workspace \
  claude-agent

Single command execution:

docker run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/home/agent/workspace \
  claude-agent -p "Review this codebase and list potential bugs"

Docker Compose for Development

For consistent development environments across teams:

# docker-compose.yml
version: '3.8'

services:
  claude:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/home/agent/workspace
      - claude-cache:/home/agent/.claude
    stdin_open: true
    tty: true

  claude-background:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/home/agent/workspace
    command: ["-p", "Monitor for changes and run tests"]
    restart: unless-stopped

volumes:
  claude-cache:

Start the stack:

docker compose up -d claude-background
docker compose run claude

Remote Execution

Cloud Server Setup

On a VPS or cloud instance:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Clone your repos
git clone https://github.com/you/project.git

# Run agent in background
docker run -d \
  --name claude-worker \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v /root/project:/home/agent/workspace \
  claude-agent -p "Implement the features in TODO.md, commit each one"

Check progress:

docker logs -f claude-worker

Parallel Agent Fleet

Run multiple agents across different repositories:

for repo in project-a project-b project-c; do
  docker run -d \
    --name "claude-$repo" \
    -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
    -v "/repos/$repo:/home/agent/workspace" \
    claude-agent -p "Update dependencies and fix breaking changes"
done

Use Cases

Scenario	Container Approach
Untrusted codebases	Full isolation, no network access
Long-running tasks	Background container on cloud server
CI/CD integration	Ephemeral containers per job
Team development	Shared compose configuration
Multi-repo refactors	Parallel agent fleet

Security Hardening

Restrict container capabilities:

docker run --rm \
  --network none \
  --read-only \
  --tmpfs /tmp \
  --cap-drop ALL \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/home/agent/workspace:ro \
  claude-agent -p "Audit this code for security issues"

This gives the agent read-only access with no network—perfect for security audits.

Next Steps

Containers separate agent work from your local machine. Combine this with task queues for automated agent orchestration at scale.

Next: Building Task Queues for Agents

Topics: claude-code security setup