Put the Agent in a Box: Running Claude Code in a Container

Running Claude Code in a Container: Containerizing AI Coding Agents for Enhanced Security

Permission fatigue presents a significant security concern when using AI coding agents like Claude Code, as repeated approval prompts can become routine, granting the agent access to sensitive files, credentials, and systems. Containers offer a solution by establishing boundaries around autonomous coding agents, limiting their potential damage through restricted mounts, non-root execution, scoped credentials, and controlled network access.

However, sandboxing is not a foolproof solution, as shared workspaces, allowed network destinations, and host-kernel vulnerabilities still require careful security controls and oversight. AI coding agents, such as Claude Code, have advanced beyond simple autocomplete, capable of reading repositories, running shell commands, installing packages, and editing files, often in an iterative loop with minimal human intervention.

To mitigate the risks associated with AI coding agents, it is essential to define the agent's scope once, in a file that the team can review and approve. This list should include the project source, language toolchain, package registry, git remote, and model inference endpoint. By limiting the agent's access to only what is necessary for its intended tasks, the potential for damage is significantly reduced.

When building a container for the agent, it is crucial to use a small image with the toolchain and CLI pinned to a specific version, and disable self-updates to ensure consistency across engineers and pipelines. Running the container as a non-root user is also recommended, as Claude Code refuses to start in its no-prompt mode as root.

Mounts should be limited to the project directory, with the agent's login state and settings stored in a named volume rather than a bind mount of the home directory. Sensitive files, such as ~/.ssh and cloud credential files, should not be mounted.

Access control is a critical aspect of containerized AI coding agents. By default, outbound traffic should be denied, and only the inference endpoint, package registry, and git host should be allowed. This can be achieved through various methods, such as using an iptables script or attaching the agent to an internal Docker network with a filtering forward proxy. Claude Code supports HTTPS_PROXY, allowing the agent container to operate without additional capabilities while maintaining a restricted allowlist.

Containers share the host kernel, so if the agent is to be run on an untrusted repository, it is advisable to use a virtual machine or microVM instead. Policy defined within the repository should be managed separately, as anyone with write access can modify the Dockerfile and introduce unintended changes. Ultimately, containers serve as boundaries, not guarantees, and their edges must be clearly defined.

By following these guidelines and using containers to containerize AI coding agents, organizations can significantly reduce the potential risks associated with these powerful tools.