Docker Environment

Docker is ideal for running Claude Code agents in an isolated, safe environment. The agent can't affect the host system, and you can run experimental code changes with peace of mind.

Why Use Docker

Situation	Without Docker	With Docker
Agent mistakes	Can corrupt host files	Only the container is affected
Dependency conflicts	Pollutes the project environment	Isolated environment
CI runs	Environment mismatches	Reproducible environment
Team sharing	"It worked on my machine..."	Guaranteed identical environment

Basic Dockerfile

A development environment that includes Claude Code:

FROM node:20-slim

# Install basic tools
RUN apt-get update && apt-get install -y \
    git \
    curl \
    python3 \
    && rm -rf /var/lib/apt/lists/*

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

# Working directory
WORKDIR /workspace

# Default git config (for commits)
RUN git config --global user.email "agent@automation.local" \
    && git config --global user.name "Claude Agent"

# Project dependencies
COPY package*.json ./
RUN npm ci

COPY . .

CMD ["bash"]

Running the Container

Basic run

# Build the image
docker build -t my-claude-env .

# Interactive run (mount the current directory)
docker run -it --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  my-claude-env \
  bash

# Run Claude Code inside the container
claude "Analyze the codebase"

Headless automation

# Run a single task and exit
docker run --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  my-claude-env \
  claude --dangerously-skip-permissions --print \
  "Add tests to reach 90% test coverage"

Hardening the Security Setup

Read-only volume

When you only need to analyze, remove write permissions:

docker run --rm \
  -v $(pwd):/workspace:ro \  # Read-only mount
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  my-claude-env \
  claude --print "Analyze security vulnerabilities"

Network isolation

# Block internet access (analyze internal code only)
docker run --rm \
  --network none \
  -v $(pwd):/workspace:ro \
  my-claude-env \
  claude --print "Review the code"

Resource limits

docker run --rm \
  --memory="2g" \
  --cpus="1.0" \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  my-claude-env \
  claude --print "Optimize it"

Docker Compose Setup

A configuration you can share with your team:

# docker-compose.yml
version: '3.8'

services:
  claude-agent:
    build: .
    volumes:
      - .:/workspace
      - claude-cache:/root/.claude  # Claude config cache
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    working_dir: /workspace
    stdin_open: true
    tty: true

  # Analysis-only (read-only)
  claude-analyzer:
    build: .
    volumes:
      - .:/workspace:ro
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    command: >
      claude --dangerously-skip-permissions --print
      "Run a security audit of the entire codebase"

volumes:
  claude-cache:

Run it:

# Interactive agent
docker-compose run claude-agent

# Automated analyzer
docker-compose run claude-analyzer

Using Docker in CI/CD

# .github/workflows/claude-agent.yml
name: Claude Code Agent

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM

jobs:
  weekly-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build agent image
        run: docker build -t claude-agent .

      - name: Run security audit
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace:ro \
            -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
            claude-agent \
            claude --dangerously-skip-permissions --print \
            "Run the weekly security audit and write a report" \
            > audit-report.md

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: weekly-audit-report
          path: audit-report.md

Git Operations Inside the Container

For Claude Code to also handle commits in Docker:

FROM node:20-slim

RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code

WORKDIR /workspace

# Git config at build time
ARG GIT_USER_EMAIL=agent@ci.local
ARG GIT_USER_NAME="Claude Agent"
RUN git config --global user.email "$GIT_USER_EMAIL" \
    && git config --global user.name "$GIT_USER_NAME" \
    && git config --global --add safe.directory /workspace

# Mount an SSH key so push is possible too
docker run --rm \
  -v $(pwd):/workspace \
  -v ~/.ssh:/root/.ssh:ro \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  claude-agent \
  claude --dangerously-skip-permissions --print \
  "Fix the bug and commit it"

Dev speed tip

To cut Docker image build time, separate node_modules into a named volume. Then a code-only change won't force a full reinstall of all dependencies.