Claude Code + Docker (2026)

The Pattern

Docker containers provide deterministic, isolated environments for Claude Code testing workflows. The cost optimization: corrupted state in a shared development environment is the leading cause of retry spirals during debugging. A Docker-based workflow eliminates state corruption by starting from a clean image for each test cycle, preventing the 30K-100K token retry spirals that occur when Claude Code fights a polluted local environment.

Why It Matters for Token Cost

When Claude Code encounters unexpected behavior caused by stale caches, leaked environment variables, or conflicting process ports, it enters a diagnostic spiral: reading logs, checking configurations, modifying code, retrying – all consuming tokens to debug a state problem rather than a code problem. These state-related spirals account for an estimated 20-30% of total debugging token spend.

A Docker-based workflow costs approximately 245 tokens per container command (Bash overhead) but prevents spirals that burn 30K-100K tokens. At Opus rates ($15/MTok input, $75/MTok output), preventing even one 50K-token state debugging spiral per week saves $0.75-$3.75/week = $3-$15/month.

The Anti-Pattern (What NOT to Do)

# Anti-pattern: Claude Code debugging state pollution on host machine
# Attempt 1: Run tests (fail due to port 3000 in use from last session)
pnpm test:integration
# Error: EADDRINUSE: address already in use :::3000
# Attempt 2: Kill process and retry (costs ~2,500 tokens)
lsof -i :3000
kill -9 <pid>
pnpm test:integration
# Error: connection refused (database not running)
# Attempt 3: Start database and retry (costs ~3,000 tokens)
pg_ctl start
pnpm test:integration
# Error: role "test_user" does not exist (database was reset)
# Attempt 4-7: More state debugging...
# Total: ~25,000 tokens to resolve a state issue, not a code issue

The Pattern in Action

Step 1: Create a Test Container Configuration

# Dockerfile.test
FROM node:22-alpine
WORKDIR /app
# Install dependencies first (cached layer)
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
# Copy source
COPY . .
# Set test environment
ENV NODE_ENV=test
ENV DATABASE_URL=postgresql://test:test@db:5432/testdb
# Health check (bounded, not infinite)
HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
  CMD wget -q --spider http://localhost:3000/health || exit 1
CMD ["pnpm", "test"]

# docker-compose.test.yml
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: testdb
    tmpfs:
      - /var/lib/postgresql/data  # RAM-based for speed
  app:
    build:
      context: .
      dockerfile: Dockerfile.test
    depends_on:
      - db
    environment:
      DATABASE_URL: postgresql://test:test@db:5432/testdb

Step 2: Encode Docker Commands in CLAUDE.md

# CLAUDE.md -- Docker-based testing
## Testing Protocol
- Run integration tests in Docker: `docker compose -f docker-compose.test.yml up --build --abort-on-container-exit 2>&1 | tail -50`
- Run unit tests on host: `pnpm test:unit 2>&1 | head -50`
- After test runs, clean up: `docker compose -f docker-compose.test.yml down -v`
- Never debug port conflicts or database state on the host -- use Docker
- If tests pass in Docker but fail on host, the issue is environment state, not code

Step 3: Bounded Test Output

# Agent-friendly test execution with bounded output
docker compose -f docker-compose.test.yml up --build --abort-on-container-exit 2>&1 | tail -50
# If tests fail, get structured output:
docker compose -f docker-compose.test.yml run --rm app pnpm test --reporter=json 2>&1 | jq '{total: .numTotalTests, passed: .numPassedTests, failed: .numFailedTests, failures: [.testResults[].assertionResults[] | select(.status == "failed") | {test: .fullName, message: .failureMessages[0][:200]}]}'

Before and After

Metric Host-Based Testing Docker-Based Testing Savings
State-related debug spirals 2-4 per week 0-1 per week 50-75% fewer
Tokens per debug spiral 25K-100K N/A (prevented) 25K-100K saved
Test environment setup tokens 500-2,000 (varies) 245 (single Docker command) 50-88%
Monthly token savings (Opus) Baseline -50K-200K tokens/month $3-$15 saved
Test reproducibility Low (state-dependent) High (deterministic) Fewer retries

When to Use This Pattern

  • Projects with integration tests that depend on databases, caches, or external services
  • Team environments where multiple developers share a machine or have divergent local setups
  • CI/CD pipelines using Claude Code for automated testing and debugging
  • Any project where “works on my machine” issues cause repeated debugging sessions

When NOT to Use This Pattern

  • Pure unit test suites with no external dependencies (Docker overhead is unnecessary)
  • Environments where Docker is not available or adds unacceptable latency
  • Quick one-file edits where the test cycle is already under 30 seconds

Implementation in CLAUDE.md

# CLAUDE.md -- Docker testing cost control
## Testing Rules
- Integration tests: ALWAYS run in Docker (`docker compose -f docker-compose.test.yml up --build`)
- Unit tests: run on host (`pnpm test:unit`)
- Cap test output: pipe through `tail -50` or use JSON reporter
- After failed integration tests: check Docker output, do not debug host state
- Clean up after each test run: `docker compose down -v`
- If Docker build fails: check Dockerfile, do not retry more than twice

Try it: Paste your error into our Error Diagnostic for an instant fix.