Para ejecutar Claude Code en Docker, inícialo en un contenedor que monte solo la carpeta de tu proyecto: el agente puede trabajar ahí con libertad mientras el resto de tu disco queda fuera de su alcance. Puedes hacerlo a mano con una imagen y una larga línea de docker run, o marcar una casilla en AgentVera y obtener el mismo contenedor ya preparado, con el inicio de sesión, la identidad de git y la propiedad de los archivos resueltos.
Esta guía cubre de qué te protege un contenedor (y de qué no), la ruta casera y cómo funcionan los agentes Docker de AgentVera.
Qué protege un contenedor y qué no
Un agente de código ejecuta comandos como tu usuario. Sin sandbox puede leer todos los archivos que tú puedes: otros repos, ~/.ssh, credenciales de la nube, dotfiles. La mayor parte del tiempo no pasa nada. El riesgo es el raro comando erróneo, una limpieza equivocada o una inyección de prompt escondida en una página web o en el README de una dependencia.
| Riesgo | Terminal normal | Contenedor Docker |
|---|---|---|
| Lee archivos fuera del proyecto | Sí | Solo lo que montas |
| Lee claves SSH y credenciales | Sí | No, salvo que se monten |
| Borra archivos fuera del proyecto | Posible | Fuera de su alcance |
| Instala herramientas globales en tu máquina | Posible | Solo dentro del contenedor, desaparecen al salir |
| Cambia o borra archivos del proyecto | Posible | Sigue siendo posible |
| Llega a internet | Sí | Sí, por defecto |
Dos filas importan más. La carpeta del proyecto sigue siendo escribible, así que haz commit a menudo o usa un git worktree. Y Docker no corta la red por sí solo: si lo quieres, necesitas reglas de red adicionales. Para una visión más amplia de las amenazas, consulta seguridad de agentes de código con IA.
Ejecutar Claude Code en Docker a mano
La ruta casera necesita tres piezas: una imagen, un comando de ejecución y una decisión sobre el inicio de sesión.
1. Construye una imagen con el CLI
Basta un Dockerfile pequeño:
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 .Añade lo que tu proyecto necesite para compilar y probar, como un compilador, un cliente de base de datos o un runtime de lenguaje.
2. Inícialo montando solo el proyecto
docker run --rm -it --init \
--user "$(id -u):$(id -g)" \
-v "$PWD":/work -w /work \
-e HOME=/home/agent --tmpfs /home/agent \
my-claude claudeQué hace cada parte:
--rmelimina el contenedor cuando Claude Code termina.--userse ejecuta con tu propio id de usuario, así que los archivos nuevos del proyecto no pertenecen a root.-v "$PWD":/workmonta el proyecto y nada más de tu disco.- Un
HOMEdesechable en tmpfs significa que el CLI tiene dónde escribir sus ajustes.
3. Resuelve el inicio de sesión y el historial
Con un home desechable, Claude Code olvida tu sesión y tus conversaciones en cada ejecución. Puedes montar una carpeta de configuración dedicada, o pasar una API key con -e ANTHROPIC_API_KEY. Pasa los secretos por nombre (-e NAME) en lugar de -e NAME=value, para que el valor no aparezca en el historial de tu shell.
Anthropic también publica una configuración devcontainer de referencia para Claude Code con firewall; si trabajas con devcontainers, lee la documentación de Claude Code al respecto.
Dónde se vuelve tediosa la ruta manual
Cada agente nuevo implica los mismos flags otra vez. El resume, las estadísticas de uso y los ajustes por proyecto viven en una carpeta que el contenedor no ve salvo que la montes. Los commits de git dentro del contenedor no tienen nombre salvo que montes ~/.gitconfig. Y si ejecutas varios agentes a la vez, acabas haciendo malabares con varios de estos comandos.
Ejecutar Claude Code en Docker con AgentVera
AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta CLIs de agentes de código en paralelo en terminales reales. Para los agentes Claude Code y Codex, el diálogo del agente tiene una casilla Run in a Docker container. Su indicación lo dice claramente: el agente solo ve la carpeta del proyecto; los demás archivos, programas y claves SSH de este ordenador permanecen cerrados para él.
Pasos
- Inicia Docker Desktop, Colima u OrbStack.
- Abre un proyecto en AgentVera y añade un agente Claude Code o Codex.
- Marca Run in a Docker container. Opcionalmente define Image, CPU y Memory (GB); deja la memoria vacía para no poner límite.
- Inicia el agente.
En el primer uso AgentVera construye su imagen de agente, agentvera/agent:1, y ves la salida de la construcción en el terminal del agente. La imagen se basa en node:22-bookworm-slim con git, ripgrep, jq, python3, make, g++ y algunas herramientas más, además de Claude Code y Codex. Si defines tu propia imagen, debe contener el comando claude o codex; una imagen que no esté en tu máquina se descarga.
La cabecera del agente muestra entonces un chip Docker, y el panel indica que se ejecuta en un contenedor Docker junto con el nombre de la imagen. También puedes pasar un agente existente a un contenedor, o sacarlo de él, editándolo; el agente se reinicia y conserva la misma conversación.
Lo que AgentVera prepara por ti
| Aspecto | Qué hace AgentVera |
|---|---|
| Archivos del proyecto | Monta la carpeta del proyecto (en un worktree, también su repositorio) |
| Sesión, resume, estadísticas | Monta la carpeta de conversaciones del CLI, así que resume, estadísticas de uso y presupuestos funcionan como siempre |
| Identidad de git | Monta ~/.gitconfig en solo lectura, así que los commits llevan tu nombre |
| Propiedad de archivos | Se ejecuta con tu id de usuario en macOS y Linux, así que los archivos no son de root |
| Carpeta home | Un home nuevo en tmpfs, que desaparece al detenerse el contenedor |
| Endurecimiento | no-new-privileges, un límite de procesos y varias Linux capabilities eliminadas |
| Secretos | Valores de entorno pasados por nombre, así que los tokens no aparecen en la lista de procesos |
| Herramientas de AgentVera | Los hooks y servidores MCP como el mapa del proyecto, el tablero y la mensajería entre agentes siguen funcionando |
Cuando el agente se detiene, el contenedor se elimina. Solo quedan los cambios de la carpeta del proyecto.
Algunas cosas que conviene saber:
- La red está abierta. En Linux el contenedor usa la red del host; en otros sistemas llega a los servidores locales de AgentVera mediante
host.docker.internal. El contenedor limita archivos, no internet. - Sesión en macOS. Claude Code guarda su sesión en el llavero de macOS, que un contenedor no puede leer, así que quizá tengas que iniciar sesión una vez dentro.
- Claude in Chrome no se usa dentro de un contenedor. El navegador de AgentVera, que funciona mediante Playwright MCP, es una opción aparte en el mismo diálogo.
- Solo agentes locales. Los agentes remotos por SSH se ejecutan en su servidor y no admiten esta opción.
Los agentes Docker forman parte del plan gratuito. La app también tiene una página aparte de gestor de Docker para tus propios contenedores y proyectos compose; consulta la página de la función Docker.
Combina el contenedor con el nivel de permisos adecuado
Un contenedor es lo que hace razonable un nivel de permisos más laxo. Los agentes de AgentVera tienen tres niveles: Ask, Auto y Full access. La indicación de Full access dice: nunca pregunta, mejor en un worktree o contenedor.
Una configuración práctica para una tarea larga:
- Crea el agente en su propio git worktree, para que sus cambios queden en una rama aparte.
- Marca Run in a Docker container.
- Elige Auto o Full access, según cuánto confíes en la tarea.
- Cuando termine, revisa el diff antes de hacer merge.
Si estás sopesando --dangerously-skip-permissions, saltarse los permisos en Claude Code cubre las contrapartidas, y ejecutar Claude Code por la noche muestra cómo encaja un contenedor en una ejecución que nadie vigila.
Lista de comprobación rápida
- El contenedor monta solo el proyecto, no tu carpeta home.
- Los archivos nuevos del proyecto te pertenecen a ti, no a root.
- Los secretos se pasan por nombre, no se incrustan en la imagen.
- El trabajo tiene commit, o el agente está en una rama de worktree.
- Sabes que la red sigue abierta y has añadido reglas si eso importa.
Descarga AgentVera para ejecutar Claude Code y Codex en contenedores junto al resto de tus agentes, o lee más en la página de agentes en Docker.