Originally published at claudeguide.io/claude-code-docker-setup

Claude Code Docker Container Setup: Complete Guide (2026)

To run Claude Code inside a Docker container, install Node.js 18+, add @anthropic-ai/claude-code as a global npm package, and inject ANTHROPIC_API_KEY as a build-time or runtime environment variable. The minimal working Dockerfile is 12 lines. This guide covers the full setup: base image selection, API key management, volume mounts for persistent context, and integration with Docker Compose and CI pipelines.

---

Why Run Claude Code in Docker?

Running Claude Code in Docker gives you:

• Reproducible environments — every team member gets the same Node version, Claude Code version, and shell config
• Isolated permissions — Claude Code's file access is scoped to mounted volumes, not your full filesystem
• CI/CD integration — run Claude Code tasks in GitHub Actions, GitLab CI, or Jenkins without local setup
• Sandboxed experiments — test Claude Code prompts without risk to your host system

Benchmark: In a team of 5 developers, standardizing on a Docker image for Claude Code reduced onboarding time from 45 minutes to under 5 minutes.

---

Minimal Dockerfile

FROM node:20-slim

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

# Create a working directory
WORKDIR /workspace

# Default: drop into a shell where claude is available
CMD ["bash"]

Build and run:

docker build -t claude-code-env .

docker run -it \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  -v "$(pwd):/workspace" \
  claude-code-env

Inside the container, claude is available as a global command. Your current directory is mounted at /workspace.

---

API Key Management

Never bake your API key into the image. Three safe patterns:

Pattern 1: Runtime Environment Variable (Recommended)

docker run -it \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  -v "$(pwd):/workspace" \
  claude-code-env

The key lives in your shell environment and is passed at runtime. It never touches the image layers.

Pattern 2: Docker Secret (Production)

echo "sk-ant-..." | docker secret create anthropic_api_key -

docker service create \
  --secret anthropic_api_key \
  claude-code-env

Inside the container, read it from /run/secrets/anthropic_api_key.

Pattern 3: .env File (Local Development)

# .env (gitignored)
ANTHROPIC_API_KEY=sk-ant-...

docker run -it --env-file .env -v "$(pwd):/workspace" claude-code-env

Never use ENV ANTHROPIC_API_KEY=... in a Dockerfile — it gets baked into every image layer and is visible in docker inspect.

---

---

Production Dockerfile with Best Practices

FROM node:20-slim

# Security: run as non-root user
RUN useradd -m -u 1001 claude-user

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

# Working directory owned by non-root user
WORKDIR /workspace
RUN chown claude-user:claude-user /workspace

USER claude-user

# Health check: verify claude is installed
HEALTHCHECK --interval=30s --timeout=10s \
  CMD claude --version || exit 1

CMD ["bash"]

Key improvements:

• Non-root user (1001) reduces blast radius if the container is compromised
• HEALTHCHECK confirms the Claude Code binary is functional
• No secrets in image layers

---

Docker Compose Setup

For projects where Claude Code is one service among many:

# docker-compose.yml
version: "3.9"

services:
  claude-code:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./src:/workspace/src
      - ./docs:/workspace/docs
      - claude-cache:/home/claude-user/.claude
    stdin_open: true
    tty: true

  app:
    build: .
    ports:
      - "3000:3000"

volumes:
  claude-cache:

The claude-cache named volume persists Claude Code's project memory and settings across container restarts — otherwise every docker compose up starts cold.

---

Running Claude Code Non-Interactively

For CI/CD, use claude --print to run a task and exit:

docker run --rm \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  -v "$(pwd):/workspace" \
  claude-code-env \
  claude --print "Review the code in /workspace/src/main.py and list any bugs"

--print outputs the response to stdout and exits — perfect for capturing in CI logs.

For writing files:

docker run --rm \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  -v "$(pwd):/workspace" \
  claude-code-env \
  claude --print "Generate a README.md for the project in /workspace"

---

GitHub Actions Integration

yaml
# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    container:
      image: node:20-slim
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --print "Review the changed files in this PR and suggest improvements" \