How to Do Docker Container Setup on Claude Code

March 8, 2026

Docker container setup in Claude Code lets you run your AI-assisted development inside an isolated, reproducible environment. Use a devcontainer.json config or run Claude Code directly inside a Docker container via the CLI. Recommended for teams, security-conscious solo devs, and anyone who needs consistent tooling across machines.

Claude Code supports Docker-based dev containers out of the box via the VS Code Dev Containers spec
Running inside a container limits Claude's filesystem and network access to what you explicitly expose
Container sessions count against your normal Claude Code usage limits, same as any other session

What is Docker container setup in Claude Code?

Claude Code is a terminal-based coding agent. When you configure it to run inside a Docker container, all file edits, bash commands, and tool calls happen within the container's filesystem and process namespace. This means Claude cannot touch files outside the mounted volume, cannot access your host's environment variables unless you pass them explicitly, and runs with whatever OS and dependencies you bake into the image.

This is especially useful when working on projects that require specific runtimes (Node 18, Python 3.11, a particular version of PostgreSQL) without polluting your host machine. It also mirrors your CI environment, so what Claude builds locally is far more likely to pass your pipeline.

How to set up a devcontainer for Claude Code

The fastest path is a .devcontainer/devcontainer.json file at the root of your project. Claude Code, like VS Code, reads this file and can operate inside the resulting container.

Step 1: create the devcontainer config

In your project root, create .devcontainer/devcontainer.json:

{
  "name": "my-project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },
  "postCreateCommand": "npm install",
  "remoteUser": "vscode"
}

The features key pulls in pre-built layers for Node, Docker-in-Docker, Python, or whatever your stack needs. The full feature catalog is maintained at containers.dev/features.

Step 2: build and open the container

If you use VS Code, the Dev Containers extension will prompt you to reopen in the container automatically. From there, open a terminal and run Claude Code as normal:

claude

Claude now operates entirely within the container's filesystem. All bash tool calls, file reads and writes, and spawned processes are contained.

Step 3: run Claude Code directly in a Docker container (no VS Code)

If you prefer a pure CLI workflow, you can mount your project into any Docker image that has Node.js and the Claude Code CLI installed:

docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  node:20 \
  npx @anthropic-ai/claude-code

Pass your API key via the environment variable. Claude Code authenticates using it and the session behaves identically to a local run. According to the Claude Code documentation, the CLI supports all the same slash commands and tool calls in a containerized session.

How to configure permissions and filesystem access

By default, Claude Code will ask for approval before running bash commands. Inside a container this is still true, but the blast radius of any command is limited to the container. You can tighten this further by running as a non-root user (set remoteUser in your devcontainer config) and by not mounting sensitive host directories.

Useful volume mount patterns

Read-only source mounts: -v $(pwd)/secrets:/run/secrets:ro lets Claude read credentials without being able to overwrite them
Named volumes for dependencies: Mount node_modules or .venv as a named volume to avoid re-installing on every container start
Separate data volume: Keep your database data directory in a named volume so docker rm doesn't wipe it

Passing environment variables safely

Avoid baking secrets into your Dockerfile. Pass them at runtime with -e VAR=value or via a .env file with --env-file .env. Claude Code's hooks system can also inject environment-specific values before commands run, keeping your config DRY.

How to use Claude Code slash commands inside Docker

All Claude Code slash commands work identically inside a container. A few that are particularly relevant for Docker workflows:

/doctor: checks that your Claude Code installation and environment are healthy. Run this first after starting a new container to confirm the CLI is wired up correctly.
/review: asks Claude to review your current diff. Useful after Claude has scaffolded a Dockerfile or docker-compose file and you want a sanity check before pushing.
/usage: shows your current token consumption for the session. Because long Docker build commands and multi-step environment setups are token-heavy, it's worth checking this mid-session so you don't hit your usage ceiling mid-task.

That last point matters. A Docker environment setup session, especially one involving dependency installs, Dockerfile iteration, and test runs, can consume a meaningful chunk of your hourly usage window. Hitting the limit mid-setup means a 5-hour lockout before you can continue.

How to monitor Claude Code usage during long container sessions

Container setup sessions tend to be longer and more token-intensive than simple code edits. You're asking Claude to write a Dockerfile, debug build errors, install dependencies, run health checks, and iterate. This adds up fast.

You can check your usage mid-session with /usage inside Claude Code, or visit claude.ai/settings/usage for your full breakdown. But both require you to context-switch out of your terminal flow.

A better option for macOS developers is Usagebar: a lightweight menu bar app that shows your Claude Code usage percentage at a glance, with smart alerts at 50%, 75%, and 90% of your limit. You see the number without switching windows. When you're in the middle of iterating on a multi-stage Dockerfile, that's exactly the kind of ambient awareness that keeps you from getting blindsided by a lockout.

Usagebar also shows you when your usage window resets, so you can decide whether to pause and wait or push through. Credentials are stored in the macOS Keychain, not in plaintext. It's pay-what-you-want, with a free tier available for students. Get Usagebar before your next long container session.

Docker Compose setup with Claude Code

For multi-service projects (app + database + cache), a docker-compose.yml is the right tool. Ask Claude to generate one with a prompt like:

"Create a docker-compose.yml for a Node.js app with PostgreSQL 15 and Redis. Use named volumes for data persistence and a .env file for credentials."

Claude will scaffold the file. You can then run docker compose up -d in your devcontainer terminal and have your full stack running. Use /review to have Claude audit the compose file for common issues (missing healthchecks, exposed ports, hardcoded secrets) before you commit it.

Connecting services by name

Inside a Docker Compose network, services are reachable by their service name. If your app service needs to connect to Postgres, the host is postgres (or whatever you named the service), not localhost. This trips people up often. Tell Claude explicitly: "use the service name as the database host, not localhost."

Key takeaways

Use .devcontainer/devcontainer.json for the cleanest integration between Claude Code and your Docker environment.
For pure CLI use, mount your project directory with -v $(pwd):/workspace and pass your API key via environment variable.
Pass secrets at runtime or via --env-file, never bake them into the image.
Use /usage or Usagebar to monitor token consumption during long setup sessions.
For multi-service stacks, Docker Compose is the right tool; use service names (not localhost) for inter-service connections.
Run /doctor after starting a new container to confirm Claude Code is healthy before beginning work.

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar