Try free

Last updated 13 October 2026

Use Claude Code inside a Docker container

Containerized development environments pose a challenge for agentic tools

When you build your code inside a Docker container, you create a wall between your tools and your source files. You want Claude Code to fix bugs or write features, but it needs access to the compilers, libraries, and binaries that live inside your specific environment. Running the agent on your host machine means it cannot run your tests or execute your build scripts because it lacks the containerized dependencies. This isolation protects your host system but stops the agent from being truly useful in a modern dev loop.

You often end up copying error messages manually from the container terminal into a host-side session to get advice. To solve this, you must run the agent inside the container itself. This allows the tool to use Bash and other utilities to interact directly with your project code as it exists in its native habitat. By putting the agent where the code runs, you enable it to verify its own work by executing the very commands that define your project's success.

Construct a Dockerfile with the necessary dependencies

Your Dockerfile needs a few specific elements to support the claude command. Start with a base image that includes Node.js and npm, as these are the primary requirements for the agent. You also need to install common terminal utilities like git, curl, and any build tools your project requires. The agent relies heavily on tools like Grep and Glob to find files and search through your codebase, so ensure these standard Unix utilities are present in the system path.

You should create a non-root user within your Dockerfile to match your host user ID. This prevents file permission issues when the agent uses the Write or Edit tools to modify your source code. If the agent creates a file as root, you might find yourself unable to edit it from your host IDE later. Set the working directory to your project root and ensure the user has full read and write access to that location before you attempt to launch a session.

Configure volume mounts for project persistence

When you start your container, you must mount your project directory from the host to the container. This ensures that any changes the agent makes using the Edit tool are reflected immediately on your local disk. Use a bind mount for this purpose. If your project is in a folder named my-app, map it to a corresponding path inside the container like /app. This allows you to keep your favorite IDE open on your host while the agent works on the same files inside the Docker environment.

Persistence for the agent itself is equally vital for a smooth experience. You should mount the ~/.claude directory from your host home folder to the container user's home folder. This directory stores your authentication state and project history. Without this mount, you would need to run /login every time you restart the container. It also ensures that sessions you start in one container are available when you use claude --resume or claude --continue in another terminal later.

Pass environment variables for authentication

The claude command requires an API key to communicate with Anthropic servers. While you can log in interactively using the /login command, it is often more efficient to pass the key through an environment variable when you start the container. This approach is particularly helpful if you are using a continuous integration system or a shared development server where interactive login is difficult. Check your environment setup to find the correct variable name used by the agent to authenticate.

Be careful with how you handle these keys in your Docker configuration. Avoid hardcoding the key directly into your Dockerfile or your docker-compose.yml file to prevent accidental leaks. Instead, use an .env file that is ignored by git or pass the variable directly through your shell at runtime. This keeps your credentials secure while giving the agent the access it needs to perform its tasks. The agent will check these variables upon startup to establish a connection with the backend.

Manage settings and project instructions

Claude Code looks for a CLAUDE.md file in your project root to understand your coding standards and build commands. When running in Docker, this file becomes even more important for orientation. You should include specific instructions about your container environment here. Tell the agent which shell to use and where the build binaries are located. If you have specific scripts to run tests or lint code, list them clearly so the agent can use the Bash tool effectively without guessing.

You can also use the .claude/settings.json file to manage how the agent behaves within the container. For example, you might want to adjust the permissions section to automatically allow certain tools like Read or Glob while requiring manual approval for Write. If you have personal preferences that differ from the project defaults, use .claude/settings.local.json. Since this file is typically ignored by version control, it allows you to customize your containerized experience without affecting other developers on your team.

Launch and interact with the agent

Once your container is running, you can enter the interactive session by executing the claude command through a terminal attach or a docker exec call. If you are returning to a project after a break, use claude --continue to pick up exactly where the agent left off. This command reloads the context of your most recent session, saving you from repeating your previous instructions. If you need to find an older task or a different branch of work, claude --resume provides a list of your previous interactions.

Inside the session, you can use slash commands to manage the state of the conversation. If the conversation becomes too long and hits context limits, use /compact to summarize the history and free up space. You can check the current costs of your session with /cost or see overall usage statistics with /usage. If the agent gets stuck or behaves unexpectedly in the container, use claude doctor to verify that the installation is healthy and all necessary terminal tools are accessible.

Navigate permission modes in a restricted environment

Docker provides a layer of safety, but you still need to control what the agent does with your files. Use Shift+Tab to cycle through the permission modes inside a session. The default mode asks for your permission before the agent executes potentially destructive tools. If you are confident in the task, you can switch to acceptEdits mode to let the agent modify files while still asking before it runs commands in the Bash tool. This balances speed with manual oversight.

For high-stakes changes or complex refactors, use the plan mode. This tells the agent to describe what it intends to do without actually executing any tools. You can review the plan and provide feedback before any code changes happen. If you are working in a throwaway container and want maximum speed, bypassPermissions allows the agent to work without any interruptions. Always remember that you can hit Escape to interrupt the agent if you see it making a mistake in the terminal output.

Streamline multiple containers with adhdTerminal

Managing multiple Docker containers for different projects can become overwhelming when each one runs its own agent. This is where adhdTerminal becomes useful. It is a native app for macOS and Windows that runs many Claude Code sessions side by side. You can have one tile for your backend container and another for your frontend container. Each tile shows whether the agent is working, waiting for you, or idle, which helps you track progress across different environments at a glance without switching tabs.

The app helps you keep your wall of tasks organized by giving each container session a name, a color, and a number. If you need to restart your computer, adhdTerminal reopens the tiles in the same place and resumes the sessions automatically. This is particularly helpful when working with Docker because the app handles the terminal connections for you. You can even check on your long-running container tasks through the free iPhone app, which mirrors your wall and lets you send the next task while you are away from your desk.

Integrate MCP servers within the container

If your project requires external data or specialized tools, you can use the Model Context Protocol (MCP). You manage these servers using the claude mcp command or the /mcp slash command inside a session. When running in Docker, you must ensure the MCP server configurations in .mcp.json point to reachable network addresses or local paths inside the container. This allows the agent to pull in documentation or interact with databases that are also containerized.

Setting up MCP servers inside your Docker environment expands the capabilities of the agent significantly. For instance, you could run a documentation server in a sibling container and connect it to your Claude Code session via the network. The agent will then use its tools to query that server whenever it needs more information about a library. This creates a powerful, self-contained ecosystem where the agent has all the context it needs to solve complex architectural problems without leaving the container.

Questions people ask

How do I handle terminal interruptions in Docker?

You can press Escape once to stop the agent from finishing a tool output or a thought. If you press Escape twice, the agent provides a list of earlier messages so you can revert the conversation to a previous state. This is useful if a bash command produces unexpected results inside your container and you need to backtrack.

Can I use custom commands inside a containerized Claude Code?

Yes, you can create markdown files in the .claude/commands directory of your project. These files define custom slash commands that the agent can recognize and execute. Ensure these files are part of your volume mount so the container can access them when you start a session.

What happens to my session history if the container is deleted?

Your session history is preserved if you have mounted the ~/.claude directory to a persistent volume or a host path. When you start a new container with the same mount, running claude --resume will show all your past sessions. This allows you to maintain a continuous workflow even if your development containers are ephemeral.

Read next

More on when it goes wrong·All posts