# How to run Claude Code in Docker as a sandbox

URL: https://agentvera.dev/en/blog/run-claude-code-in-docker/ · Published: 2026-10-24

Run Claude Code in Docker so the agent sees only your project folder: a do-it-yourself docker run recipe, its limits, and the one-checkbox container in AgentVera.

**In short:**

- A container limits what the agent can read and change on disk to the folders you mount; it does not cut the network unless you add that yourself.
- By hand you need an image with the CLI, the project mounted, your user id and a place for the login; AgentVera does all of it with one checkbox.
- In AgentVera, Claude Code and Codex agents can run in a container that is removed when the agent stops; only changes in the project folder remain.

**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](/en/blog/git-worktree-parallel-agents/). 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](/en/blog/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:

```dockerfile
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-code
```

```bash
docker 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

```bash
docker run --rm -it --init \
  --user "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  -e HOME=/home/agent --tmpfs /home/agent \
  my-claude claude
```

What each part does:

1. `--rm` removes the container when Claude Code exits.
2. `--user` runs as your own user id, so new files in the project are not owned by root.
3. `-v "$PWD":/work` mounts the project, and nothing else from your disk.
4. A throwaway `HOME` on 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](/en/) 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

1. Start Docker Desktop, Colima or OrbStack.
2. Open a project in AgentVera and add a Claude Code or Codex agent.
3. Tick **Run in a Docker container**. Optionally set **Image**, **CPU** and **Memory (GB)**; leave memory empty for no limit.
4. 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](/en/features/docker/).

## 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:

1. Create the agent in its own git worktree, so its changes stay on a separate branch.
2. Tick **Run in a Docker container**.
3. Choose **Auto** or **Full access**, depending on how much you trust the task.
4. When it finishes, review the diff before you merge.

If you are weighing `--dangerously-skip-permissions`, [skipping permissions in Claude Code](/en/blog/claude-code-skip-permissions/) covers the trade-offs, and [running Claude Code overnight](/en/blog/run-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](/en/download/) to run Claude Code and Codex in containers next to the rest of your agents, or read more on the [agents in Docker](/en/features/agents-in-docker/) page.

## Frequently asked questions

**Why run Claude Code in Docker at all?** An agent on your machine can read anything your user can: other projects, SSH keys, cloud credentials, browser data. In a container it sees only the folders you mount, so a bad command or a prompt injection has far less to reach.

**Does a Docker container cut the agent off from the internet?** Not by default. A normal container has network access. Docker limits files and processes; if you also want to restrict the network you need your own firewall rules or network setup. AgentVera agent containers keep the network open so the CLI can reach its API.

**Which agents can AgentVera run in a container?** Claude Code and Codex agents that run on your own computer. Remote agents over SSH run on their server and do not use this option. The container needs Docker Desktop, Colima or OrbStack running.

**Do I have to log in again inside the container?** Usually not, because AgentVera mounts the CLI’s conversation folder into the container. On macOS Claude Code keeps its login in the keychain, which a container cannot read, so you may need to sign in once inside it.

**Is it safe to use full access mode inside a container?** It is much safer than on the bare machine, which is why AgentVera’s Full access hint says it is best in a worktree or container. The agent can still change or delete files in the project folder, so keep your work committed and review the diff.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/