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.

Proven prompt patterns for Claude Code workflows

Power Prompts ($29) includes 50 tested prompts for Docker setup, debugging, refactoring, and CI automation — with exact commands you can copy-paste.

Get Power Prompts — $29

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

# .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" \
            > review-output.txt
          cat review-output.txt

      - name: Upload review
        uses: actions/upload-artifact@v4
        with:
          name: claude-review
          path: review-output.txt

Store your API key in GitHub Actions secrets as ANTHROPIC_API_KEY. See Claude Code GitHub Actions CI/CD for a full CI/CD pipeline example.

Volume Mount Strategy

Mount only what Claude Code needs:

Avoid mounting your entire home directory — Claude Code will read files it finds, and large directories slow down context loading.

Debugging Common Issues

"claude: command not found" inside container

The npm install -g succeeded but the global bin path isn't in PATH. Fix:

ENV PATH="/root/.npm-global/bin:${PATH}"
RUN npm config set prefix '/root/.npm-global' && \
    npm install -g @anthropic-ai/claude-code

"API key not set" error

Check the key is being passed correctly:

docker run --rm -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" claude-code-env env | grep ANTHROPIC

If empty, ANTHROPIC_API_KEY isn't set in your host shell. Run export ANTHROPIC_API_KEY=sk-ant-... first.

Slow context loading

If Claude Code is slow to start, you've likely mounted a large directory. Add a .claudeignore file at the workspace root:

node_modules/
.git/
dist/
*.log

For more on managing Claude Code context, see Claude Code Complete Guide.

Frequently Asked Questions

What Node.js version does Claude Code require in Docker?

Claude Code requires Node.js 18 or higher. The node:20-slim image is recommended — it's smaller than the full Node image (210MB vs 1GB) while still including everything Claude Code needs. Avoid node:alpine as it uses musl libc which can cause compatibility issues with some npm packages.

Can I run Claude Code in a Docker container without an internet connection?

No. Claude Code makes API calls to Anthropic's servers for every inference. The container needs outbound HTTPS access to api.anthropic.com. For air-gapped environments, you would need a network proxy that routes traffic to the Anthropic API.

How do I persist Claude Code's project memory in Docker?

Mount a named volume to /root/.claude (or /home/claude-user/.claude if running as a non-root user). This directory stores Claude Code's project context, settings, and conversation history. Without this mount, memory resets every time the container starts.

Is it safe to use Claude Code in Docker for sensitive codebases?

Docker isolation limits Claude Code's file access to mounted volumes. For maximum security: run as a non-root user, mount only the directories Claude Code needs, use Docker secrets for API key management, and review all changes before committing. Claude Code does not exfiltrate code — it only sends the context you provide in prompts to the Anthropic API.

How do I update Claude Code to the latest version in Docker?

Rebuild your image with --no-cache to force a fresh npm install: docker build --no-cache -t claude-code-env .. Alternatively, pin a specific version: npm install -g @anthropic-ai/claude-code@1.x.x to avoid unexpected updates.

Can I run multiple Claude Code instances in parallel with Docker?

Yes. Each container is isolated, so you can run parallel containers for different tasks — e.g., one reviewing frontend code, another reviewing backend. Be aware of API rate limits: multiple parallel instances count against your same Anthropic account limits. See Claude Agent SDK Guide for orchestration patterns.

50 copy-paste prompts for Docker and CI/CD workflows

Power Prompts ($29) covers Docker setup, code review automation, CI pipeline integration, and 45 more tested patterns.

Get Power Prompts — $29