Last updated 13 October 2026
Run Claude Code inside a Docker container
Local environment drift makes agent behavior unpredictable
When you share a project with a team, the local environment of each developer is slightly different. One person has a specific version of a build tool, while another uses an older system library. Claude Code relies on the tools available in its environment to perform tasks like Read, Edit, and Bash. If the environment is inconsistent, the agent might suggest commands that work for you but fail for your colleague. This leads to broken pull requests and wasted time debugging environment issues instead of writing code. You need a way to ensure that the agent always sees the same set of tools and the same file structure regardless of the machine it runs on.
A containerized development environment solves this by packaging the entire toolchain into a single image. When the agent uses the Bash tool to run a test or compile a binary, it does so inside the container. This means the result is reproducible. If the agent successfully builds the project inside the container on your machine, it will also build it on a CI server or a teammate's computer. This predictability is vital for an agent that takes autonomous actions. Without a consistent environment, you spend more time correcting the agent's environment specific mistakes than you do shipping features.
Constructing a Dockerfile for the coding agent
To get started, you need a Dockerfile that includes Node.js since that is the runtime for the tool. Use a standard Debian or Ubuntu based Node image to ensure compatibility with common build tools. Inside the Dockerfile, you must install git because the agent uses it to track changes and manage state. You also need to install the agent itself by running the npm install command for the global package. This makes the command "claude" available within the container shell. Ensure you also install any project specific dependencies like compilers for C++, runtimes for Python, or utility libraries like curl and jq.
Your Dockerfile should also create the necessary directory structure for configuration. The agent looks for settings in the home directory under a hidden folder. You should create this folder in the Dockerfile and set the appropriate permissions so the agent can write to it. It is also a good practice to set the working directory to the root of your project. This ensures that when you start the container and run "claude", it immediately finds your source code and any local configuration files like CLAUDE.md. By defining the environment in a Dockerfile, you move the complexity of setup from a manual checklist to a version controlled script.
Managing authentication and environment variables
Running the agent inside a container requires a way to handle your Anthropic API key without hardcoding it into the image. The best approach is to use environment variables. When you run the container, you can pass the key using the standard flag for environment variables. This keeps your credentials secure while allowing the agent to authenticate with the back end. You can also manage other settings like the preferred model or permission levels through these variables if you want to bypass manual interactive configuration every time you rebuild the container.
Once the key is available, you can use the "/login" command within the session if necessary, but providing the key via the environment is usually sufficient for automated or ephemeral containers. If you are working in a team, you might use a secret management service to inject these keys into the container at runtime. This ensures that no one accidentally commits a key to the repository. The agent will use this identity to track usage and cost, which you can monitor by running "/cost" or "/usage" at any time during your session. Proper credential management is the first step toward a secure and portable agent setup.
Persisting session history and user settings
Containers are ephemeral by default, meaning any data stored inside them is lost when the container stops. For a coding agent, this is a problem because you lose the history of your conversations and the state of your work. The agent stores its global settings in ~/.claude/settings.json and its session history in other files within that hidden directory. To keep your history across container restarts, you must mount a host directory to the container path for the home folder settings. This allows you to use the "claude --resume" command to pick up an old conversation even if you have destroyed and recreated the container.
You also need to persist the project specific settings and the local session data. These are typically stored in a .claude folder at the root of your repository. Since you are likely mounting your project code as a volume into the container, this folder should persist naturally on your host machine. This setup allows the agent to remember context across different runs. If the session becomes too large and hits context limits, you can use the "/compact" command to summarize the history while preserving the essential information. Mapping these volumes correctly ensures that the agent feels like a continuous part of your workflow rather than a fresh instance every time you start your terminal.
Implementing project specific rules with CLAUDE.md
The agent relies on CLAUDE.md files to understand how to interact with your code. In a Docker environment, these files are even more important because they tell the agent which containerized tools to use. You should place a CLAUDE.md file in the root of your project with clear instructions on build commands, test suites, and code style. If your project has subdirectories with different requirements, you can place additional CLAUDE.md files in those folders. The agent will read these to adapt its behavior to the specific part of the tree it is working on.
Inside these files, specify the exact Bash commands the agent should run. Since the agent is running inside a container, these commands will execute in that controlled environment. For example, if you have a specific test runner installed in the container, the CLAUDE.md file should instruct the agent to use that exact command. This removes ambiguity and prevents the agent from trying to use tools that are only available on your host OS but missing from the container. By standardizing these instructions, you ensure that every instance of the agent, regardless of who is running the container, follows the same protocol.
Executing commands and managing interactive sessions
Running the agent inside Docker can be done in two main ways: interactive and non-interactive. For an interactive session, you run the container with a terminal attached and execute the "claude" command. This allows you to use slash commands like "/model" to switch versions or "/permissions" to check what the agent is allowed to do. You can use the "/terminal-setup" command to ensure the container shell handles the agent interface correctly. This mode is best for active development where you are providing constant feedback to the agent.
For non-interactive tasks, you can use the "claude -p" flag followed by a prompt. This is useful for automated scripts or CI pipelines where you want the agent to perform a single task and then exit. For example, you might want the agent to review a specific file or generate a summary of changes. If a session is interrupted, you can use "claude --continue" to resume the most recent interaction in that folder. The agent also supports flags like "claude --resume" to let you choose from a list of previous sessions stored in your persisted volumes. This flexibility makes the tool suitable for both manual exploration and automated maintenance.
Integrating model context protocol servers
The agent can extend its capabilities using MCP servers. In a Docker setup, you manage these with the "claude mcp" command or by editing the .mcp.json configuration file. If you are running MCP servers inside the same container, you need to ensure they are properly installed and accessible. If you are running them in separate containers, you will need to handle the networking so the agent can communicate with them. This allows the agent to use extra tools that might not be built into the core package.
When an MCP server is active, the agent can use it to fetch external data or interact with other services. You can check the status of these connections using the "/mcp" slash command within a session. If you need to add new capabilities to your containerized agent, adding an MCP server is often cleaner than modifying the base Docker image. It keeps the core environment stable while allowing for modular extensions. Always remember to check the costs associated with these extra tool calls by using "/cost" frequently, as complex tool use can increase the number of tokens used in a session.
Running multiple isolated environments simultaneously
One of the biggest advantages of containerization is the ability to run multiple projects side by side without them interfering with each other. You can have one container running a legacy Node.js project and another running a modern Python application, each with its own instance of the agent. This isolation prevents library conflicts and keeps your host machine clean. However, managing many terminal windows for different containers can become visually overwhelming and difficult to track, especially when multiple agents are working on long tasks at the same time.
This is where adhdTerminal becomes useful for a developer. It allows you to run many Claude Code sessions side by side as tiles on a single wall. Each tile shows you whether an agent is working, waiting for your input, or finished with its task. Instead of hunting through tabs to see which containerized agent has finished its build, you can see the status of every session at a glance. You can name each tile based on the container or project it represents, making it much easier to manage a complex microservices architecture where multiple agents are active across different Docker environments.
Handling file permissions and system access
Permissions are a critical aspect of running an agent inside a container. By default, the agent will ask for permission before performing sensitive actions like writing to files or running shell commands. You can change these modes using Shift+Tab inside a session to cycle through default, acceptEdits, plan, and bypassPermissions. In a containerized environment, you might be more comfortable using bypassPermissions because the agent is already isolated from your main host system. This allows the agent to work faster without stopping for every single edit.
You can fine tune these permissions in the .claude/settings.json file. This file lets you allow or deny specific tools like Write or Bash on a per-tool basis. Since the agent respects .gitignore, it will not attempt to read or modify files that you have excluded from your repository. If the agent behaves unexpectedly or gets stuck, you can use the "claude doctor" command to check the health of the installation and its access to the file system. Using adhdTerminal helps here too, as its iPhone app can mirror your wall of containers and notify you if an agent is stuck waiting for a permission or has completed a task while you are away from your desk.
Questions people ask
How do I update the agent inside a running container?
You should run the "claude update" command inside the container shell to get the latest version of the tool. If you want a permanent update, modify your Dockerfile to use the latest version and rebuild the image. This ensures that every new container you start begins with the most recent features and bug fixes.
Can the agent access the internet from inside the Docker container?
Yes, as long as your Docker network configuration allows outbound traffic. The agent needs internet access to communicate with the Anthropic API and to use tools like WebFetch or WebSearch. If you are behind a corporate proxy, you must configure the standard environment variables like HTTP_PROXY inside the container for the agent to work.
What happens if I forget to mount the settings volume?
If you do not mount a volume for ~/.claude, the agent will treat every container start as a brand new user. You will have to log in again with "/login" if your session token is not preserved, and you will lose access to your previous conversation history. Your custom slash commands in .claude/commands and subagents in .claude/agents will also be missing unless they are part of the project volume.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.