Can I run Claude Code in Docker?

Yes. Claude Code runs inside Docker containers as a Node.js CLI. Install Node.js 18+ in your Docker image, install Claude Code with npm, and pass your ANTHROPIC_API_KEY as an environment variable. This is useful for reproducible environments, CI/CD pipelines, and sandboxed execution.

How do I set up Claude Code in a VS Code dev container?

Create a .devcontainer/devcontainer.json file that uses a Node.js base image, installs Claude Code as a postCreateCommand, and forwards your ANTHROPIC_API_KEY. When you open the project in VS Code, it automatically builds the container with Claude Code pre-installed and ready to use.

Is it safe to run Claude Code in a container?

Running Claude Code in a container is actually more secure than running it directly on your machine. The container provides sandboxed file system access, network isolation, and resource limits. Claude can only access files mounted into the container. This is the recommended approach for running Claude Code in automated or untrusted environments.

Claude Code with Docker & Dev Containers: Complete Setup Guide (2026)

Why Run Claude Code in Docker?

Benefit	Description
Reproducible environments	Every team member gets the same Node.js version, tools, and Claude Code configuration
Sandboxed file access	Claude can only read/write files you mount into the container
Network isolation	Control which external services Claude can reach
Clean environments	No pollution of your host system; easily reset to clean state
CI/CD integration	Run Claude Code in GitHub Actions, GitLab CI, or any container-based pipeline
Resource limits	Cap CPU and memory usage for Claude Code processes

Basic Dockerfile

The simplest way to containerize Claude Code:

Dockerfile

FROM node:22-slim # Install Claude Code globally RUN npm install -g @anthropic-ai/claude-code # Create workspace directory WORKDIR /workspace # Default command: interactive Claude Code session ENTRYPOINT ["claude"]

# Build the image
$ docker build -t claude-code .

# Run Claude Code with your project mounted
$ docker run -it --rm \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
claude-code

Extended Dockerfile with Common Tools

For most projects, you'll want git, language runtimes, and other tools:

Dockerfile

FROM node:22-slim # Install system dependencies RUN apt-get update && apt-get install -y \ git \ curl \ python3 \ python3-pip \ jq \ gh \ && rm -rf /var/lib/apt/lists/* # Install Claude Code RUN npm install -g @anthropic-ai/claude-code # Install common dev tools RUN npm install -g typescript tsx prettier eslint # Set up workspace WORKDIR /workspace # Copy CLAUDE.md if it exists (optional) COPY CLAUDE.md* ./ ENTRYPOINT ["claude"]

Layer caching

Put the npm install -g @anthropic-ai/claude-code line early in your Dockerfile. This layer gets cached and won't re-run unless you change it, making subsequent builds fast.

VS Code Dev Containers

Dev containers give you a full VS Code environment inside Docker. Claude Code works seamlessly in the integrated terminal.

Basic devcontainer.json

.devcontainer/devcontainer.json

{ "name": "Claude Code Dev", "image": "mcr.microsoft.com/devcontainers/typescript-node:22", "features": { "ghcr.io/devcontainers/features/github-cli:1": {} }, "postCreateCommand": "npm install -g @anthropic-ai/claude-code", "containerEnv": { "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}" }, "customizations": { "vscode": { "extensions": [ "anthropic.claude-code" ], "settings": { "terminal.integrated.defaultProfile.linux": "bash" } } } }

With this config, opening your project in VS Code will:

Build a container with Node.js 22 and TypeScript
Install the GitHub CLI
Install Claude Code globally
Forward your local ANTHROPIC_API_KEY into the container
Install the Claude Code VS Code extension

Custom Dockerfile Dev Container

For more control, use a custom Dockerfile:

.devcontainer/devcontainer.json

{ "name": "My Project Dev", "build": { "dockerfile": "Dockerfile", "context": ".." }, "postCreateCommand": "npm install", "containerEnv": { "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}", "NODE_ENV": "development" }, "mounts": [ "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached" ], "remoteUser": "node" }

.devcontainer/Dockerfile

FROM node:22 # Install Claude Code and dev tools RUN npm install -g @anthropic-ai/claude-code typescript tsx # Install Python (for projects that need it) RUN apt-get update && apt-get install -y python3 python3-pip gh \ && rm -rf /var/lib/apt/lists/* WORKDIR /workspace

Mount your ~/.claude directory

The mounts config above shares your Claude Code authentication and settings between host and container. This means you only need to authenticate once.

Docker Compose Setup

For projects with services (databases, caches, APIs), use Docker Compose to give Claude Code access to the full stack:

docker-compose.yml

services: app: build: . volumes: - .:/workspace - ${HOME}/.claude:/root/.claude environment: - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} - DATABASE_URL=postgres://user:pass@db:5432/myapp - REDIS_URL=redis://cache:6379 depends_on: - db - cache stdin_open: true tty: true db: image: postgres:16 environment: POSTGRES_USER: user POSTGRES_PASSWORD: pass POSTGRES_DB: myapp volumes: - pgdata:/var/lib/postgresql/data cache: image: redis:7-alpine volumes: pgdata:

# Start all services and run Claude Code
$ docker compose run --rm app

# Or start services in background, then attach Claude
$ docker compose up -d db cache
$ docker compose run --rm app claude

Now Claude Code can interact with your database and cache just like it would in production.

Sandboxed Execution

Docker provides natural sandboxing for Claude Code. Here's how to lock it down for automated or untrusted workloads:

Read-Only Source Code

# Mount source as read-only, with a writable output directory
$ docker run -it --rm \
-v $(pwd):/workspace:ro \
-v $(pwd)/output:/output \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
claude-code "review the code and write your findings to /output/review.md"

Network Restrictions

# Only allow access to Anthropic API
$ docker run -it --rm \
--network=none \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
claude-code

Network=none blocks the API

Using --network=none blocks ALL network access including the Anthropic API. For true isolation, create a custom network that only allows traffic to api.anthropic.com.

Resource Limits

# Limit CPU and memory
$ docker run -it --rm \
--cpus=2 \
--memory=4g \
-v $(pwd):/workspace \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
claude-code

CI/CD with Docker

Use your Claude Code Docker image in CI pipelines for consistent automated reviews and fixes:

.github/workflows/claude-review.yml

name: Claude Code Review on: pull_request jobs: review: runs-on: ubuntu-latest container: image: node:22-slim steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Install Claude Code run: npm install -g @anthropic-ai/claude-code - name: Review PR env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | claude --model claude-haiku-4-5 \ "Review this PR diff for bugs and security issues. Be concise." \ < <(git diff origin/main...HEAD)

Best Practices

Image Optimization

Use node:22-slim instead of node:22 (300MB vs 1GB)
Use multi-stage builds if you need build tools only during setup
Pin the Claude Code version: npm install -g @anthropic-ai/claude-code@1.x.x
Clean up apt caches: && rm -rf /var/lib/apt/lists/*

Security

Never bake API keys into images — always pass via environment variables or secrets
Run as non-root user when possible (USER node)
Use .dockerignore to exclude .env, node_modules, and .git
Mount source code as read-only for review-only workflows
Set --memory and --cpus limits to prevent runaway processes

Performance

Mount ~/.claude to persist authentication and settings across container restarts
Use Docker volumes for node_modules to avoid slow bind mounts on macOS
Pre-install project dependencies in the image for faster startup

Troubleshooting

Authentication Issues

If Claude Code can't authenticate inside Docker:

Verify ANTHROPIC_API_KEY is set: docker run --rm -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude-code claude --version
For browser auth, mount ~/.claude from your host to share the auth token
Check the API key hasn't expired or been revoked

File Permission Issues

If Claude can't write to mounted directories:

The container user must match the file owner. Use --user $(id -u):$(id -g)
Or use remoteUser: "node" in devcontainer.json and ensure the mount has correct permissions

Slow Performance on macOS

Docker file mounts on macOS are slower than native. Mitigate with:

Use consistency=cached or consistency=delegated mount options
Put node_modules in a Docker volume instead of a bind mount
Consider using OrbStack instead of Docker Desktop for better macOS performance

Frequently Asked Questions

Can I use browser login inside Docker?

Not directly, since Docker doesn't have a browser. Use ANTHROPIC_API_KEY for container authentication. Alternatively, authenticate on your host machine first, then mount ~/.claude into the container to share the session.

Does Claude Code work with Podman?

Yes. Claude Code works with any OCI-compatible container runtime including Podman, containerd, and nerdctl. Replace docker with podman in all commands.

Can I use Claude Code in Kubernetes?

Yes. Deploy Claude Code as a Job or CronJob in Kubernetes. Pass ANTHROPIC_API_KEY via a Kubernetes Secret and mount your code as a volume or use git-sync init container.

How do I keep Claude Code updated in containers?

Pin to a specific version in your Dockerfile and update it periodically. For always-latest behavior, use npx @anthropic-ai/claude-code as the entrypoint, but this adds startup latency.

Claude Code + Docker & Dev Containers