To run Claude Code in Docker, start it in a container that mounts only your project folder: the agent can then work freely there while the rest of your disk stays out of reach. You can do that by hand with an image and a long docker run line, or tick one box in AgentVera and get the same container set up for you, with login, git identity and file ownership handled.
This guide covers what a container protects you from (and what it does not), the do-it-yourself route, and how AgentVera’s Docker agents work.
What a container protects, and what it does not
A coding agent runs commands as your user. Without a sandbox it can read every file you can: other repos, ~/.ssh, cloud credentials, dotfiles. Most of the time that is fine. The risk is the rare bad command, a confused cleanup, or a prompt injection hidden in a web page or a dependency’s README.
| Risk | Plain terminal | Docker container |
|---|---|---|
| Reads files outside the project | Yes | Only what you mount |
| Reads SSH keys and credentials | Yes | No, unless mounted |
| Deletes files outside the project | Possible | Not reachable |
| Installs global tools on your machine | Possible | Only inside the container, gone on exit |
| Changes or deletes files in the project | Possible | Still possible |
| Reaches the internet | Yes | Yes, by default |
Two rows matter most. The project folder is still writable, so commit often or use a git worktree. And Docker does not cut the network on its own: if you want that, you need extra network rules. For a wider look at the threats, see AI coding agent security.
Run Claude Code in Docker by hand
The do-it-yourself route takes three pieces: an image, a run command and a decision about the login.
1. Build an image with the CLI
A small Dockerfile is enough:
FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
git curl ca-certificates ripgrep openssh-client less procps jq python3 \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-codedocker build -t my-claude .Add whatever your project needs to build and test, such as a compiler, a database client or a language runtime.
2. Start it with only the project mounted
docker run --rm -it --init \
--user "$(id -u):$(id -g)" \
-v "$PWD":/work -w /work \
-e HOME=/home/agent --tmpfs /home/agent \
my-claude claudeWhat each part does:
--rmremoves the container when Claude Code exits.--userruns as your own user id, so new files in the project are not owned by root.-v "$PWD":/workmounts the project, and nothing else from your disk.- A throwaway
HOMEon tmpfs means the CLI has somewhere to write its settings.
3. Deal with the login and history
With a throwaway home, Claude Code forgets your login and conversations each run. You can mount a dedicated config folder instead, or pass an API key with -e ANTHROPIC_API_KEY. Pass secrets by name (-e NAME) rather than -e NAME=value, so the value does not show up in your shell history.
Anthropic also publishes a reference devcontainer setup for Claude Code with a firewall; if you work in devcontainers, read the Claude Code docs for it.
Where the manual route gets tedious
Every new agent means the same flags again. Resume, usage stats and per-project settings live in a folder the container does not see unless you mount it. Git commits inside the container have no name unless you mount ~/.gitconfig. And if you run several agents at once, you are juggling several of these commands.
Run Claude Code in Docker with AgentVera
AgentVera is a desktop app for macOS, Windows and Linux that runs coding agent CLIs side by side in real terminals. For Claude Code and Codex agents, the agent dialog has a Run in a Docker container checkbox. Its hint says it plainly: the agent sees only the project folder; other files, programs and SSH keys on this computer stay closed to it.
Steps
- Start Docker Desktop, Colima or OrbStack.
- Open a project in AgentVera and add a Claude Code or Codex agent.
- Tick Run in a Docker container. Optionally set Image, CPU and Memory (GB); leave memory empty for no limit.
- Start the agent.
On first use AgentVera builds its agent image, agentvera/agent:1, and you watch the build output in the agent’s terminal. The image is based on node:22-bookworm-slim with git, ripgrep, jq, python3, make, g++ and a few other tools, plus Claude Code and Codex. If you set your own image, it must contain the claude or codex command; an image that is not on your machine is pulled.
The agent header then shows a Docker chip, and the pane says it is running in a Docker container along with the image name. You can also switch an existing agent into or out of a container by editing it; the agent restarts and keeps the same conversation.
What AgentVera sets up for you
| Concern | What AgentVera does |
|---|---|
| Project files | Mounts the project folder (for a worktree, also its repository) |
| Login, resume, stats | Mounts the CLI’s conversation folder, so resume, usage stats and budgets work as usual |
| Git identity | Mounts ~/.gitconfig read-only, so commits carry your name |
| File ownership | Runs as your user id on macOS and Linux, so files are not owned by root |
| Home folder | A fresh home on tmpfs, gone when the container stops |
| Hardening | no-new-privileges, a process limit and several Linux capabilities dropped |
| Secrets | Environment values passed by name, so tokens do not appear in the process list |
| AgentVera tools | Hooks and MCP servers such as the project map, the board and agent messaging keep working |
When the agent stops, the container is removed. Only the changes in the project folder remain.
A few things to know:
- Network is open. On Linux the container uses the host network; elsewhere it reaches AgentVera’s local servers through
host.docker.internal. The container limits files, not the internet. - macOS login. Claude Code stores its login in the macOS keychain, which a container cannot read, so you may need to sign in once inside it.
- Claude in Chrome is not used inside a container. The AgentVera browser, which runs through Playwright MCP, is a separate option in the same dialog.
- Local agents only. Remote agents over SSH run on their server and do not take this option.
Docker agents are part of the free plan. The app also has a separate Docker manager page for your own containers and compose projects; see the Docker feature page.
Pair the container with the right permission level
A container is what makes a looser permission level reasonable. AgentVera agents have three levels: Ask, Auto and Full access. The Full access hint reads: never asks, best in a worktree or container.
A practical setup for a long task:
- Create the agent in its own git worktree, so its changes stay on a separate branch.
- Tick Run in a Docker container.
- Choose Auto or Full access, depending on how much you trust the task.
- When it finishes, review the diff before you merge.
If you are weighing --dangerously-skip-permissions, skipping permissions in Claude Code covers the trade-offs, and running Claude Code overnight shows how a container fits a run nobody is watching.
Quick checklist
- The container mounts only the project, not your home folder.
- New files in the project are owned by you, not root.
- Secrets are passed by name, not baked into the image.
- Work is committed, or the agent is on a worktree branch.
- You know the network is still open, and you have added rules if that matters.
Download AgentVera to run Claude Code and Codex in containers next to the rest of your agents, or read more on the agents in Docker page.