Claude Code Docker: ejecuta agentes de IA en contenedores

Los agentes de IA autónomos para programar son potentísimos. Navegan por tu sistema de archivos, ejecutan comandos de shell, hacen commits y modifican archivos, todo sin que escribas una sola línea de código. Pero ese poder trae una duda legítima: ¿qué pasa si algo sale mal? ¿Y si el agente modifica un archivo de configuración que no debería tocar o instala un paquete que entra en conflicto con tu sistema?

La respuesta a la que llegan la mayoría de desarrolladores con mentalidad de producción es Docker, y es la misma a la que yo volvía una y otra vez después de una sesión concreta en la que Claude Code, con toda su buena intención, “limpió” el archivo .env de mi proyecto porque parecía no usarse. (Sí se usaba). 

Los contenedores te dan una frontera clara entre el agente y tu máquina host, y esa frontera es lo que hace que las ejecuciones desatendidas del agente se sientan seguras en lugar de estresantes. 

En este tutorial te guiaré para ejecutar Claude Code dentro de Docker: desde construir una imagen base mínima hasta orquestar una aplicación multiservicio con Docker Compose. Al final tendrás un flujo de trabajo seguro y repetible que podrás usar en cualquier proyecto.

Si te interesan los modelos más nuevos de Anthropic, te recomiendo leer nuestras guías sobre Claude Opus 4.6 y Claude Sonnet 4.6.

Cómo se integra Claude Code con Docker

Para entender por qué Docker encaja tan bien con Claude Code, conviene repasar brevemente qué hace cada herramienta.

Claude Code es la herramienta de línea de comandos de Anthropic para programación con agentes, lanzada con disponibilidad general en mayo de 2025. Vive en tu terminal, lee tu base de código y ejecuta tareas (refactorizar, escribir tests, gestionar flujos de trabajo con git) a partir de indicaciones en lenguaje natural. Nuestro tutorial completo de Claude Code 2.1 cubre todo lo que necesitas saber.

Docker es una plataforma para empaquetar y ejecutar aplicaciones en contenedores ligeros y aislados que comparten el kernel del sistema operativo host, pero mantienen límites estrictos de procesos y sistema de archivos. Si eres totalmente nuevo en Docker, te recomiendo nuestro guía sobre la plataforma gratuita Play with Docker y experimentar allí.

Claude Code necesita un entorno para ejecutarse. Docker aporta uno reproducible y desechable. Esa combinación es potente, pero para sacarle todo el partido hay que entender el modelo de ejecución, los valores predeterminados de seguridad y qué enfoque de despliegue encaja con tu situación.

Arquitectura de contenedores y flujo de ejecución

Empecemos por cómo funciona realmente una sesión de Claude Code en contenedor a nivel de petición.

1. Lanzas una indicación desde tu terminal en el host. 
2. Docker arranca el contenedor con la CLI de Claude Code preinstalada y tu espacio de trabajo montado como volumen. 
3. Claude Code lee archivos desde ese montaje, analiza la base de código, ejecuta comandos dentro del espacio de procesos aislado del contenedor y escribe la salida de vuelta al volumen montado. 
4. Cuando termina la sesión, el sistema de archivos efímero del contenedor (todo lo que esté fuera del montaje) se descarta.

La clave aquí es distinguir entre el estado efímero y el persistente. Todo lo que se escriba en el contenedor fuera del volumen montado se borra en la limpieza. Tu espacio de trabajo, que vive en el host y se monta dentro, permanece. 

Esto significa que dependencias temporales, artefactos de build e instalaciones de herramientas desaparecen, pero tus archivos de proyecto quedan exactamente como los dejó Claude. Esta separación me resulta realmente tranquilizadora: antes de entenderla, me quedaba mirando las sesiones del agente con nervios. Ahora lanzo una tarea y me voy a por café.

Modelos de seguridad y valores seguros por defecto

Teniendo claro el flujo de ejecución, vale la pena precisar qué protege realmente el aislamiento de Docker y qué no.

El aislamiento del sistema de archivos es la principal ganancia de seguridad. Claude Code solo puede leer y escribir archivos en las rutas que montes explícitamente. Si no las montas en el contenedor, tus claves SSH, credenciales de ~/.aws, variables de entorno del host y archivos de configuración del sistema son invisibles para el agente a menos que decidas exponerlos. Sin embargo, esa protección solo se mantiene si configuras bien tus montajes.

Una regla crítica: nunca montes el socket de Docker del host (/var/run/docker.sock) dentro del contenedor de Claude Code. Si el agente puede hablar con el daemon de Docker en tu host, podría lanzar contenedores con privilegios, salir de la sandbox por completo y obtener acceso de root a tu máquina. 

Este es un camino de escalada de privilegios bien conocido y sin una buena justificación. Lo he visto sugerido en algunos Dockerfiles de la comunidad como forma de permitir que el agente “gestione contenedores”, y cada vez que lo veo me entran ganas de enviarle al autor un mensaje muy contundente.

Elegir la vía de despliegue adecuada

Más allá de los valores de seguridad por defecto, hay otra decisión antes de escribir código: ¿qué modelo de despliegue encaja con tu caso? Hay tres opciones principales, y no son intercambiables.

Para la mayoría de tareas (ejecutar el agente contra un único repo, depurar un script, refactorizar un módulo), un sandbox sencillo con Docker es el valor por defecto más seguro. 

Docker Compose tiene sentido cuando Claude Code necesita interactuar con una base de datos, una API o un servicio frontend en ejecución. 

Los devcontainers son la mejor opción para entornos estandarizados de equipo con extensiones de IDE preconfiguradas. Cabe destacar que el devcontainer de referencia oficial de Anthropic incluye un cortafuegos integrado que restringe las conexiones salientes a una lista de permitidos, y ese aislamiento es lo que permite ejecutar Claude Code con --dangerously-skip-permissions en modo totalmente desatendido. 

En este tutorial cubriremos tanto el sandbox de un solo contenedor como una configuración con Compose.

Configuración de un contenedor Docker para Claude Code

Ahora que la arquitectura y las opciones de despliegue están claras, aseguremos que el entorno esté bien configurado antes de escribir código. He visto saltarse este paso más veces de las que puedo contar, y es la razón más común por la que tutoriales como este fallan a mitad.

Requisitos de sistema y software

Esto es todo lo que necesitas antes del primer docker build:

• Docker Desktop (macOS o Windows) o Docker Engine (Linux), con el daemon activo. En macOS y Windows, la virtualización debe estar habilitada en la BIOS/firmware. En Linux, añade tu usuario al grupo docker con sudo usermod -aG docker $USER, o antepone sudo a cada comando de Docker.

• Node.js v18 o posterior en tu máquina host, ya que la CLI de Claude Code es un paquete de npm. Confírmalo con node --version.

• Una clave de API de Anthropic, que puedes generar en la Claude Console.

Verifica que Docker está sano con una comprobación rápida antes de seguir:

docker run --rm hello-world

Si ves Hello from Docker!, el daemon responde correctamente y puedes continuar.

Autenticación y variables de entorno

Con el daemon confirmado, lo siguiente son las credenciales. Inyectar tu clave de API de Anthropic como variable de entorno en tiempo de ejecución es mucho más seguro que iniciar sesión de forma interactiva dentro del contenedor. 

Esto lo aprendí por las malas: los inicios de sesión interactivos pueden “hornear” credenciales en capas del contenedor o en historiales de shell que persisten en disco mucho después de que te hayas olvidado.

El patrón correcto es pasar la clave en tiempo de ejecución usando -e:

docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" my-claude-image

Fíjate en que hago referencia a $ANTHROPIC_API_KEY desde mi shell del host. La clave nunca se escribe en el Dockerfile, nunca se comitea al control de versiones y nunca aparece en ninguna capa de la imagen. Defínela una vez en tu perfil de shell (~/.zshrc o ~/.bashrc) y fluirá de forma limpia a cada ejecución del contenedor a partir de entonces.

Inicialización del espacio de trabajo

Con la autenticación lista, el último paso de preparación es crear un espacio de trabajo limpio. Yo siempre creo un directorio dedicado para cada sesión del agente en vez de apuntar a un proyecto existente, porque elimina el riesgo de que el agente se meta en código adyacente que no pretendías tocar.

mkdir ~/claude-docker-tutorial
cd ~/claude-docker-tutorial
echo "# My Project" > README.md
echo "def hello(): return 'world'" > app.py

Mantén este directorio limpio. No copies tu archivo .env real ni ninguna credencial. El workspace debe contener solo el código en el que quieres que el agente trabaje, y nada más. Con esto listo, ya podemos construir.

Ejecutar Claude Code en Docker

Con el entorno configurado y los conceptos claros, toca construir. Esta sección recorre los pasos: primero, una imagen mínima de un solo contenedor; después, una sesión funcional en sandbox; y por último, una pila completa con Compose. Cada paso se apoya en el anterior, así que te recomiendo seguirlos en orden.

1. Crear la imagen base del contenedor

Todo en esta sección se basa en los principios de seguridad que comentamos antes. Aquí tienes un Dockerfile mínimo que los pone en práctica, instalando la CLI de Claude Code sobre una imagen base ligera de Node.js:

FROM node:20-slim

# Create a non-root user for safer execution
RUN useradd -m -u 1001 claude

# Install Claude Code CLI globally
RUN npm install -g @anthropic-ai/claude-code

# Set the working directory
WORKDIR /workspace

# Switch to non-root user
USER claude

ENTRYPOINT ["claude"]

Hay algunas decisiones de diseño que merece la pena explicar. Uso node:20-slim en lugar de node:20-alpine porque Alpine utiliza la libc musl, que a veces da problemas de compatibilidad con paquetes nativos de npm. 

Yo me topé con este problema a la primera con Alpine: la CLI de Claude Code se instalaba bien, pero se caía al primer arranque con un error de enlazador críptico que me llevó una hora rastrear hasta musl. 

La variante slim se basa en Debian: ligera y fiable, sin ese drama. Además, creo un usuario dedicado claude y cambio a él antes del entrypoint, lo que hace que el proceso del agente se ejecute sin privilegios de root y limita lo que puede hacer incluso dentro del contenedor.

Construye la imagen con:

docker build -t claude-code:latest .

En la primera build, Docker descarga la imagen base e instala la CLI. En compilaciones posteriores sin cambios en el Dockerfile, verás “CACHED” junto a cada capa, haciendo que las reconstrucciones sean casi instantáneas una vez establecida la base.

2. Lanzar una sesión de sandbox aislada

Con la imagen lista, toca ejecutar la primera sesión real. 

Operaciones de solo lectura

Para tareas de solo lectura como listar o resumir archivos, el comando básico basta:

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  claude-code:latest \
  "List the files in this workspace and describe what each one does."

La opción -v $(pwd):/workspace monta tu directorio actual en el contenedor, así que el comando funciona desde cualquier carpeta de proyecto. La bandera --rm elimina el contenedor automáticamente al salir.

Operaciones de escritura

Las operaciones de escritura requieren dos banderas adicionales. 

La opción -u $(id -u):$(id -g) pasa el UID y GID de tu usuario del host al contenedor, dando al proceso claude permiso para escribir en tus archivos montados. Sin esto, recibirás un error de sistema de archivos de solo lectura porque el usuario claude del contenedor no coincide con la propiedad de archivos en tu host. 

La opción --dangerously-skip-permissions omite los avisos interactivos de aprobación de Claude Code, necesarios cuando se ejecuta de forma no interactiva dentro de un contenedor. El propio aislamiento de Docker es lo que lo hace seguro.

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  -u $(id -u):$(id -g) \
  claude-code:latest \
  --dangerously-skip-permissions \
  "Add a docstring to the hello function in app.py."

Operación de escritura con Claude Code en Docker

Luego comprueba tu archivo local: cat app.py. Si ves el docstring, el montaje del volumen funciona en ambos sentidos y estás listo para escalar a una configuración multiservicio.

3. Orquestar una app multiservicio

El sandbox de un solo contenedor funciona bien para tareas aisladas, pero el desarrollo real a menudo implica varios servicios en ejecución simultánea. Aquí es donde Docker Compose brilla.

La configuración de abajo enlaza el agente de Claude Code con un servicio web y una base de datos PostgreSQL, un montaje representativo para muchos proyectos backend:

services:
  claude:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    depends_on:
      db:
        condition: service_healthy
    networks:
      - app-network

  web:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - ./workspace:/app
    command: python -m http.server 8080
    ports:
      - "8080:8080"
    networks:
      - app-network

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Ten en cuenta que se omite version, ya que está obsoleto en Docker Compose moderno y mostrará una advertencia si lo incluyes. 

Otros dos detalles a destacar:

Primero, el servicio claude monta .:/workspace (el directorio actual) en lugar de un subdirectorio. Usar ./workspace requeriría que exista una subcarpeta aparte, y el agente vería un workspace vacío. 

Segundo, se pasa explícitamente DATABASE_URL para que el agente sepa cómo alcanzar Postgres. Sin ello, Claude no tiene cadena de conexión y te la pedirá.

La línea user: "${UID}:${GID}" aplica el mismo override de UID/GID del host que usamos en los comandos independientes de docker run, para que las escrituras de archivos funcionen correctamente. Expórtalos antes de ejecutar:

export UID=$(id -u) GID=$(id -g)

El servicio claude no tiene un command persistente, así que a diferencia de web y db, no está pensado para ejecutarse continuamente. Arranca primero los servicios de soporte y luego invoca Claude bajo demanda con docker compose run:

# Start the database and web service
docker compose up -d web db

# Run a one-off Claude task
docker compose run --rm \
  claude \
  --dangerously-skip-permissions \
  "Check the database connection and summarize the schema in README.md."

Claude Code con Docker Compose

Arranca primero los servicios de soporte con docker compose up -d web db y luego observa sus logs con docker compose logs -f. Fíjate en depends_on con condition: service_healthy. 

Me lo salté en un proyecto inicial y pasé 20 minutos persiguiendo errores de conexión a la base de datos hasta que me di cuenta de que Claude había arrancado antes de que Postgres estuviera listo. La comprobación de salud no cuesta nada y evita justo ese dolor de cabeza.

4. Gestionar la limpieza de sesiones

Cuando termines tu sesión, la limpieza es tan importante como la preparación. Los contenedores huérfanos consumen memoria e interfieren con ejecuciones futuras y, por mi experiencia, este es el paso que más se omite hasta que algo empieza a comportarse raro.

Estos son los comandos que más usarás y cuándo tirar de cada uno:

La bandera -v en docker compose down es con la que hay que tener cuidado. Borra los volúmenes con nombre, lo que significa que cualquier dato de base de datos que hayas acumulado en Postgres desaparecerá. Solo la uso cuando de verdad quiero empezar de cero. En caso contrario, con docker compose down a secas basta.

Integraciones de Claude Code con Docker y resolución de problemas

Con el flujo principal funcionando con limpieza, veamos cómo ampliarlo y cómo depurarlo cuando algo falla.

Integrar modelos locales y extensiones

Claude Code permite redirigir la inferencia a cualquier endpoint local compatible con Anthropic mediante ANTHROPIC_BASE_URL. Docker Model Runner, integrado en Docker Desktop, expone precisamente una API así, haciendo que la integración sea nativa del ecosistema Docker.

Descarga un modelo y apunta Claude Code al endpoint local:

docker model pull ai/smollm2
ANTHROPIC_BASE_URL=http://localhost:12434 claude --model ai/smollm2 "List the files of the repository."

Este es un patrón distinto al enfoque de contenedor en sandbox descrito antes. Aquí, Claude Code se ejecuta en tu host y la inferencia permanece local mediante Docker Model Runner, así que ninguna llamada a la API sale de tu máquina.

Más allá de los modelos locales, puedes extender el alcance de Claude Code a través de servidores MCP (Model Context Protocol). Si no estás familiarizado, nuestra guía de MCP es un gran recurso para empezar.

El MCP Toolkit de Docker ofrece más de 200 servidores MCP preconstruidos y contenedorizados que cubren GitHub, Jira, Supabase y más, dando a Claude Code acceso con permisos a esas herramientas sin exponer credenciales de API en crudo. 

En conjunto, estos dos puntos de extensión te dan control significativo tanto sobre dónde ocurre la inferencia como sobre a qué servicios externos puede acceder el agente.

Optimizar el rendimiento de las builds

A medida que tu Dockerfile crece, el tiempo de build puede convertirse en cuello de botella. Las builds multietapa lo solucionan separando la instalación de la imagen de runtime:

# Build stage
FROM node:20-slim AS builder
RUN npm install -g @anthropic-ai/claude-code

# Runtime stage
FROM node:20-slim
COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
COPY --from=builder /usr/local/bin/claude /usr/local/bin/claude
RUN useradd -m -u 1001 claude
USER claude
WORKDIR /workspace
ENTRYPOINT ["claude"]

El orden de las capas importa tanto como la estructura, y esto lo hice mal más tiempo del que me gustaría admitir. 

Las instrucciones que cambian rara vez (como instalar paquetes del sistema) van arriba. Las que cambian a menudo (como copiar archivos fuente) van abajo. Así maximizas los aciertos de caché y conviertes reconstrucciones de 30 segundos en casi instantáneas.

Depurar fallos de integración comunes

Incluso con una configuración bien planteada, las cosas se rompen. Aquí tienes un bucle de depuración repetible para los problemas que me encuentro más a menudo. Síntoma primero y luego el comando a ejecutar:

• Salida de red bloqueada: Claude Code no puede llegar a la API de Anthropic. Ejecuta docker run --rm alpine wget -qO- https://api.anthropic.com para verificar salida a Internet. Si falla, revisa docker network inspect bridge en busca de configuración de proxy.

• Montajes de volumen incorrectos: Claude Code indica que no encuentra archivos. Ejecuta docker run --rm -v $(pwd):/workspace alpine ls /workspace. Un listado vacío significa que tu ruta es incorrecta. Confirma que el directorio existe antes de nada.

• Caché de build obsoleta: Has actualizado tu Dockerfile pero el comportamiento no cambia. Fuerza una reconstrucción completa con docker build --no-cache -t claude-code:latest ..

• Fallos de conexión entre servicios en Compose: Un servicio no puede alcanzar a otro. Los servicios se comunican por sus nombres de servicio (db, web), no por localhost. Ejecuta docker compose exec web ping db para probar alcance. Un ping fallido indica que los servicios no están en la misma red.

Conclusión

Ejecutar Claude Code dentro de Docker te da algo realmente valioso: la libertad de dejar que un agente autónomo trabaje a su aire sabiendo que lo que puede tocar está estrictamente acotado. 

En este tutorial he explicado cómo construir una imagen mínima sin root, gestionar volúmenes de workspace, orquestar aplicaciones multiservicio con Docker Compose y diagnosticar los fallos de integración más comunes. 

La configuración me llevó una tarde hasta dejarla fina, y cambió por completo cómo afronto el desarrollo asistido por agentes. Delego tareas completas en lugar de vigilar cada paso, y el límite que impone Docker es lo que lo hace posible.

A partir de aquí, merece la pena explorar dos direcciones:

Primero, investiga plantillas de devcontainer para tu equipo. El devcontainer de referencia de Claude Code en GitHub incluye un cortafuegos preconfigurado que restringe las conexiones salientes a dominios de confianza. Segundo, experimenta con Docker MCP Toolkit para dar a Claude Code acceso estructurado a tus herramientas existentes: GitHub, bases de datos, sistemas de gestión de proyectos y más.

Por último, pon un recordatorio para actualizar periódicamente tus imágenes base. Con el tiempo acumulan vulnerabilidades y un rápido docker pull node:20-slim seguido de una reconstrucción lleva solo unos minutos.

Si te interesa desarrollar aplicaciones de IA, te recomiendo encarecidamente inscribirte en nuestro itinerario de habilidades AI Engineering with LangChain. Los cursos son nativos de IA, así que tendrás un profesor personal que te recoge justo en tu nivel y te ayuda a alcanzar tus objetivos a tu ritmo.