Running CLI Agents Inside Docker

Most advice about agent safety is fighting the wrong battle. It tells you to restrict what the agent can do — deny this command, gate that edit, approve everything one prompt at a time. That's useful, but it treats the symptom. The real fix for "what if the agent does something destructive" isn't tighter restrictions on your host machine. It's not running the agent on your host machine at all. A CLI agent Docker setup changes the entire question: an agent inside a locked-down container can't wreck your laptop, leak your SSH keys, or touch anything you didn't explicitly hand it, no matter what it does.

Here's the contrarian part — once the agent is properly contained, you can safely give it more autonomy, not less. The isolation is what makes the freedom safe.

Quick-Start: Copy This Right Now

The core idea: the container is the sandbox. Mount only the repo, deny network access, and let the agent work.

docker run --,[object Object], -it \
  -v ,[object Object], -w /work \
  --network none \
  node:22 bash -c ,[object Object],

What this does: Spins up a throwaway container with only your current directory mounted, no network access, and the agent installed inside it. The agent can do anything it wants to /work — which is just your repo — and nothing at all to your actual machine. When the container exits, it's gone.

That's the whole foundation. Everything else is refinement of what to mount, what network to allow, and how much autonomy to grant inside the box.

⚡ Pro tip: Mount your repo, never your home directory. The most common containerization mistake is mounting too much — bind-mounting $HOME or / hands the agent your SSH keys, cloud credentials, and browser data, defeating the entire point. Mount exactly the working directory the task needs and nothing else.

Understanding the Variables

Three variables determine how much isolation your container actually provides.

The mount scope decides what the agent can see and change. A bind mount of the repo means the agent's world is the repo. Mount more and you've widened the blast radius; mount less and you've contained it. This is the single most important setting.

The network policy decides whether the agent can reach out. --network none means the agent physically cannot exfiltrate code or pull an unpinned package — the container has no route to the internet. Some tasks need network access (installing dependencies, calling the model API), so the practical middle ground is a proxy that allows only the specific endpoints required.

The autonomy level decides how much you gate inside the box. And here's the reframe: because the container is the real boundary, the permission gates inside it can loosen. Bypassing per-command approval — which would be reckless on your host — becomes reasonable inside a network-isolated, repo-only container, because the worst the agent can do is mess up files you can regenerate.

[object Object],
docker run --,[object Object], -it -v ,[object Object], -w /work --network none node:22 \
  bash -c ,[object Object],

What this does: Runs the agent with per-command approval disabled — but inside a container with no network and only the repo mounted. On your host this flag would be dangerous; here it's the intended pattern, because the container, not the prompt-by-prompt approval, is doing the containment. The autonomy is bounded by walls the agent can't reach through.

⚠️ Common mistake: Skipping permissions on your host machine because you saw the pattern used in a container. The --dangerously-skip-permissions flag is reasonable only inside a properly isolated container. On your host, with your home directory and network fully accessible, it's exactly as dangerous as it sounds. The flag is safe because of the box, not on its own.

CLI Agent Docker Setup, Step by Step

Let's build a reusable containerized agent setup.

Step one: write a Dockerfile so the environment is reproducible, not assembled by hand each time.

FROM node:22
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /work

What this does: Defines a reproducible image with the agent pre-installed. Everyone on the team runs the identical environment, and a new machine is one docker build away from a working setup instead of a manual install dance.

Step two: pass credentials as an environment variable, never bake them into the image.

docker run --,[object Object], -it -v ,[object Object], \
  -e ANTHROPIC_API_KEY --network none agent-img claude

What this does: Forwards your API key from the host environment into the container at runtime without writing it into the image layers. Baking a key into an image is a leak waiting to happen the moment that image is shared or pushed; passing it at runtime keeps it out of the build.

Step three: for tasks needing dependencies, allow a scoped network instead of full access. A proxy or an allowlist of package-registry and API endpoints lets npm install and the model API through while still blocking arbitrary exfiltration.

Step four: treat containers as ephemeral. --rm deletes the container on exit, so every run starts clean. A per-task container means one task's mess can never contaminate the next.

⚡ Pro tip: Use a fresh container per task for genuinely autonomous runs. An ephemeral container is a clean room — the agent can install anything, break anything, litter the filesystem, and it all vanishes on exit. This is what makes it safe to let a contained agent run with high autonomy: the environment is disposable, so "it made a mess" costs nothing.

The Performance Cost Nobody Mentions

Containerizing an agent isn't free, and the costs surprise people who expected isolation to come for free. Two of them are worth planning around.

The first is filesystem overhead on bind mounts. On macOS and Windows especially, bind-mounted volumes are noticeably slower than native disk, and an agent that reads and writes across a large repo does a lot of filesystem work. A big test suite that runs in thirty seconds on the host can crawl inside a container with a bind-mounted repo. It's not a dealbreaker, but it's real, and it's worst exactly where agents do the most I/O.

The second is repeated setup cost. Installing the agent and dependencies fresh in every ephemeral container adds up. The fix is to bake everything into a prebuilt image so each run starts from a warm, ready environment rather than reinstalling from scratch.

[object Object],
docker build -t agent-img .
docker run --,[object Object], -it -v ,[object Object], -w /work --network none agent-img claude

What this does: Builds the image with the agent and tooling already installed, so docker run skips the install step entirely. The reproducibility of a container without paying the setup cost on every single invocation.

The honest tradeoff: ephemeral-per-task containers are safest but slowest to spin up; a long-lived warm container is faster for iterative interactive work but accumulates state you have to trust. Use ephemeral for autonomous runs where safety dominates, and a warm container for hands-on iteration where speed matters and you're watching.

⚡ Pro tip: For iterative interactive work, reuse one warm container across the session instead of a fresh one per command. You keep the isolation while avoiding the per-run startup tax, and because you're actively watching an interactive session, the accumulated state is far less of a risk than it would be in an unattended run. Save ephemeral containers for the autonomous jobs where clean-every-time actually matters.

Pro-Level Variations

A security-conscious team runs every agent task in a network-isolated container against a local model, so neither the code nor the prompts ever leave their infrastructure — the container handles filesystem isolation, the local model handles data isolation.

A platform team ships a shared devcontainer definition in the repo, so anyone opening the project gets an identical, pre-isolated agent environment with the mounts and network policy already configured correctly. New engineers inherit the safe setup instead of assembling their own.

A developer running risky autonomous experiments — "refactor this however you think best" — does it in an ephemeral container where high autonomy is safe, reviews the resulting diff from outside the container, and discards the container regardless of outcome.

⚡ Pro tip: Review the agent's changes from the host, not inside the container. Because the repo is bind-mounted, the changes appear on your host filesystem in real time, so you can run git diff and your normal review from your trusted environment while the untrusted agent stays boxed. You get the agent's output without ever giving your review tools access to its environment.

Troubleshooting Common Issues

If the agent can't reach the model API, your network policy is too strict — --network none blocks the API call too. Switch to a scoped proxy that allows the API endpoint while still denying general internet access.

If changes aren't appearing on your host, check the bind mount — a named volume or a copy-in instead of a bind mount keeps the agent's changes trapped inside the container. For a review-from-host workflow you specifically want a bind mount of the working directory.

⚠️ Common mistake: Running the container as root and bind-mounting the repo, then finding the agent's new files are root-owned on your host. Run the container as your user id, or fix ownership after, so the containerized agent doesn't leave you a directory full of files you need sudo to edit.

Your Turn

A CLI agent Docker setup flips the safety model from restriction to isolation: the container is the sandbox, so mounting only the repo and denying network access lets you safely grant the agent more autonomy inside the box, not less. The scary flags become reasonable behind container walls, and ephemeral per-task containers make "it made a mess" a non-event.

The Dockerfile, the mount-and-network flags, the credential-passing pattern, the review-from-host workflow — these are the same for every CLI agent Docker task. Save them in PromptABCD so your next autonomous run starts inside a proper box instead of on your host machine, where the scary flags actually are scary.