Docker + Claude Code te da un entorno sandbox donde Claude Code opera libremente sin tocar tu máquina host. Obtienes aislamiento completo, configuraciones reproducibles con docker compose up, y la capacidad de dar permisos amplios al sistema de archivos de forma segura — porque el peor caso es simplemente reconstruir un contenedor.
"Funciona en mi máquina" es la frase más desmoralizante del desarrollo de software. Versiones de Node.js que no coinciden, variables de entorno sutilmente diferentes, conflictos de dependencias — todo equipo ha perdido horas con esto. Las migraciones de Prisma que fallan por diferencias en la versión de OpenSSL, por ejemplo, son un clásico en GitHub Issues.
Combinar Docker con Claude Code resuelve esto de forma limpia. Delega toda la configuración del entorno a Claude Code y obtén un entorno de desarrollo equivalente a producción en minutos. Así es cómo.
¿Por Qué Claude Code + Docker Es una Combinación Tan Poderosa?
Claude Code es una excelente herramienta de generación de código, pero opera directamente en tu máquina host — instalando paquetes, modificando archivos de configuración, ocupando puertos. En la mayoría de los casos eso está bien, pero para refactorizaciones a gran escala o cambios exploratorios, los efectos secundarios a nivel de host pueden ser un problema.
Añadir Docker cambia la ecuación por completo.
Aislamiento completo — No importa cuántos archivos Claude Code reescriba dentro de un contenedor, nada se filtra al host. Si Claude Code rompe la mitad de los imports durante una refactorización dentro de un contenedor, con docker compose down && docker compose up vuelves al punto inicial de inmediato. Si pasara en el host, sería para entrar en pánico.
Reproducibilidad garantizada — docker compose up le da a cada miembro del equipo un entorno idéntico. El problema de "funciona en mi máquina" desaparece.
Paridad con producción — Desarrolla sobre la misma imagen de SO y las mismas versiones de middleware que producción. La divergencia del entorno de staging se reduce drásticamente.
Permisos amplios y seguros para Claude Code — Puedes dar a Claude Code acceso amplio al sistema de archivos dentro de un contenedor sin preocuparte por dañar el host. La configuración oficial de devcontainer de Anthropic incluso soporta --dangerously-skip-permissions para operación completamente desatendida, combinada con reglas de firewall que restringen el tráfico saliente solo a dominios permitidos.
¿Cómo Configuras un DevContainer para Claude Code?
La funcionalidad DevContainer de VS Code es el enfoque estándar para desarrollo basado en Docker. Claude Code puede leer esta configuración y ejecutarse dentro del contenedor. Anthropic también publica un devcontainer de referencia con funciones de seguridad integradas — úsalo directamente o como base para personalizar.
Requisitos previos
- Docker Desktop (o Docker Engine + Docker Compose)
- VS Code con la extensión Dev Containers
- CLI de Claude Code
Pasos de configuración
Crea el directorio .devcontainer/ en la raíz de tu proyecto.
mkdir -p .devcontainer
Crea .devcontainer/devcontainer.json.
{
"name": "Mi Proyecto Dev",
"dockerComposeFile": "docker-compose.yml",
"service": "app",
"workspaceFolder": "/workspace",
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "22"
},
"ghcr.io/devcontainers/features/git:1": {}
},
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"bradlc.vscode-tailwindcss"
],
"settings": {
"editor.formatOnSave": true
}
}
},
"postCreateCommand": "npm install && npm run build",
"remoteUser": "node"
}
Crea .devcontainer/docker-compose.yml. Nota: el campo version está obsoleto en Docker Compose V2 y debe omitirse.
services:
app:
build:
context: ..
dockerfile: .devcontainer/Dockerfile
volumes:
- ..:/workspace:cached
- node_modules:/workspace/node_modules
ports:
- "3000:3000"
environment:
- NODE_ENV=development
command: sleep infinity
volumes:
node_modules:
Crea .devcontainer/Dockerfile.
FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y \
git \
curl \
&& rm -rf /var/lib/apt/lists/*
# Instalar Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /workspace
Abre la carpeta del proyecto en VS Code con "Reopen in Container" y el entorno se levanta automáticamente. La primera compilación tomó unos 3 minutos en mi MacBook M2 — los inicios siguientes son menos de 10 segundos gracias al caché de capas de Docker.
¿Cómo Haces que Claude Code Genere docker-compose.yml?
Los proyectos reales frecuentemente involucran bases de datos, caches, colas de mensajes y otros servicios. Escribir el docker-compose.yml completo desde cero toma tiempo. Claude Code maneja esto bien — he conseguido que genere configuraciones precisas para proyectos con más de 5 servicios al primer intento.
Este es el tipo de prompt que obtiene excelentes resultados:
Crea un docker-compose.yml para este proyecto Next.js.
Requisitos:
- Next.js 15 (Node.js 22)
- PostgreSQL 16
- Redis 7
- Entorno de desarrollo (hot reload habilitado)
- Sin configuración de producción
- Health checks en todos los servicios
- Variables de entorno cargadas desde .env.local
Un output típico de Claude Code:
services:
app:
build:
context: .
dockerfile: Dockerfile.dev
volumes:
- .:/app
- /app/node_modules
- /app/.next
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgresql://postgres:password@db:5432/myapp_dev
- REDIS_URL=redis://redis:6379
env_file:
- .env.local
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
command: npm run dev
db:
image: postgres:16-alpine
volumes:
- postgres_data:/var/lib/postgresql/data
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=password
- POSTGRES_DB=myapp_dev
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres_data:
redis_data:
Health checks, dependencias de servicios, volúmenes nombrados — todo correctamente configurado. A partir de ahí, puedes iterar: "Cambia PostgreSQL a la versión 17," "Añade un servicio de backup," y Claude Code actualiza el archivo correctamente.
¿Cómo Ejecutas Claude Code de Forma Segura Dentro de un Contenedor?
Ejecutar Claude Code dentro de un contenedor es principalmente sobre contener el radio de explosión de operaciones destructivas. Cuando le pides a Claude Code que "elimine estos archivos" o "refactorice todo en este directorio," hacerlo dentro de un contenedor significa que el peor caso es perder el contenedor — no el sistema de archivos de tu máquina host.
Inicia Claude Code dentro del contenedor
# Entra al contenedor en ejecución
docker exec -it myproject-app-1 bash
# Ejecuta Claude Code desde dentro
claude
Si estás usando DevContainers en VS Code, la terminal integrada ya está dentro del contenedor. No se necesitan pasos adicionales.
Para flujos de trabajo completamente desatendidos (pipelines de CI, procesamiento por lotes), el devcontainer oficial soporta --dangerously-skip-permissions combinado con un firewall que solo permite tráfico a npm registry, GitHub y la API de Claude. Esto significa que Claude Code puede ejecutarse sin prompts de permisos mientras permanece aislado de la red.
# Dentro del devcontainer oficial (con firewall activado)
claude --dangerously-skip-permissions
Pasar credenciales de API de forma segura
Claude Code necesita tu clave de API. Nunca la codifiques directamente.
# docker-compose.yml
services:
app:
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
# .env en el lado del host (¡añádelo a .gitignore!)
ANTHROPIC_API_KEY=sk-ant-...
Pasar credenciales desde el entorno del host al contenedor mantiene los secretos fuera del control de versiones y fuera de la imagen Docker.
¿Qué Necesitas Saber Sobre Docker + Claude Code en WSL2?
En Windows con WSL2 (Windows Subsystem for Linux), hay una trampa que debes evitar absolutamente. Uso esta configuración exacta a diario en WSL2 Ubuntu — el rendimiento es excelente una vez que evitas el error común.
Configuración recomendada
- Usa Docker Desktop para Windows con el backend WSL2
- Mantén tus proyectos en el sistema de archivos WSL2 (
/home/username/) - No coloques proyectos bajo
/mnt/c/(el sistema de archivos de Windows)
Montar rutas del sistema de archivos de Windows en volúmenes Docker causa una degradación severa del rendimiento. Cuando cometí este error al principio, el hot reload de Next.js tardaba 8 segundos por cada guardado. Mover el proyecto a ~/projects/ en el sistema de archivos WSL2 lo redujo a menos de 1 segundo. Si tienes problemas de desconexión con Claude Code en WSL2, consulta nuestra guía dedicada.
Instala Claude Code en WSL2
# Ejecuta dentro de WSL2 (Ubuntu)
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @anthropic-ai/claude-code
Integración VS Code + WSL2
La extensión Remote - WSL te permite editar archivos WSL2 desde Windows VS Code. La extensión Dev Containers también funciona dentro de WSL2. El resultado es una experiencia nativa de Windows respaldada por un entorno Linux.
¿Cómo Aíslas Completamente los Entornos de Desarrollo por Proyecto?
Al trabajar en múltiples proyectos, dar a cada uno su propia configuración DevContainer crea un aislamiento limpio y completo. Incluso trabajando con diferentes versiones de Node.js en distintos proyectos, cambiar entre ellos es simplemente "Reopen in Container" sin conflictos de versiones.
projects/
├── project-a/
│ ├── .devcontainer/
│ │ └── devcontainer.json # Node.js 20 + PostgreSQL 16
│ └── src/
├── project-b/
│ ├── .devcontainer/
│ │ └── devcontainer.json # Node.js 22 + MySQL 8
│ └── src/
└── project-c/
├── .devcontainer/
│ └── devcontainer.json # Python 3.12 + Redis
└── src/
El DevContainer de cada proyecto puede incluir su propia configuración CLAUDE.md, haciendo que toda la configuración de trabajo sea portable. Prompts específicos del proyecto, patrones prohibidos y convenciones de código viajan con el repositorio.
{
"postCreateCommand": "npm install && echo 'Dev environment ready for Claude Code'"
}
El verdadero beneficio llega cuando un nuevo miembro del equipo se incorpora. git clone → abrir en VS Code → "Reopen in Container." Ese es todo el proceso de onboarding. Claude Code funciona de manera idéntica para todos.
¿Cómo Configuras Servidores MCP Dentro de un Contenedor?
Los servidores MCP (Model Context Protocol) también pueden ejecutarse dentro del contenedor, encapsulando el acceso a herramientas de Claude Code junto con todo lo demás.
// .claude/settings.json (dentro del contenedor)
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/workspace"
]
},
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://postgres:password@db:5432/myapp_dev"
]
}
}
}
Restringir el servidor de sistema de archivos a /workspace limita el acceso a archivos de Claude Code solo al directorio del proyecto.
El servidor de postgres permite que consultas como "verifica el esquema de la tabla users" o "encuentra el problema N+1 en estos endpoints" sean manejadas por Claude Code directamente contra tu base de datos real. Uso esta combinación en 32blog — Claude Code puede leer el esquema de la base de datos y generar APIs basadas en Prisma sin que tenga que describir el modelo de datos manualmente.
¿Cómo Usas Claude Code para Prevenir la Divergencia Dev/Prod?
La divergencia dev/prod generalmente sucede gradualmente: una configuración de conveniencia añadida durante el desarrollo nunca llega a producción. Claude Code puede detectar esto activamente.
Compara docker-compose.yml (desarrollo) con
k8s/deployment.yaml (producción).
Busca diferencias en variables de entorno,
configuraciones de puertos y health checks.
Presenta las discrepancias en una tabla.
También puedes pedirle a Claude Code que genere y mantenga tu pipeline de CI/CD.
Crea .github/workflows/deploy.yml:
- Build de imagen Docker y push a GHCR
- Despliegue usando docker-compose.prod.yml
- Ejecutar health checks después del despliegue
- Notificación a Slack en caso de fallo
Al delegar la configuración del entorno a Claude Code, obtienes detección continua de la divergencia sutil que los humanos tienden a pasar por alto.
¿Cómo Integrar Pipelines CI/CD con Entornos Docker?
Cuando las imágenes Docker difieren entre dev y CI, aparece "funciona en local pero falla en CI." Claude Code puede unificar las configuraciones usando Dockerfiles multi-stage.
Prompt para Dockerfile multi-stage:
Escribe un Dockerfile para este proyecto con estas condiciones:
- stage base: Node.js 22 Alpine + dependencias compartidas
- stage dev: hereda de base, incluye devDependencies, hot reload
- stage ci: hereda de base, ejecución de tests y build
- stage prod: hereda de base, solo assets construidos
Estructura del Dockerfile generado:
# base
FROM node:22-alpine AS base
WORKDIR /app
COPY package*.json ./
# dev
FROM base AS dev
RUN npm ci
CMD ["npm", "run", "dev"]
# ci
FROM base AS ci
RUN npm ci
COPY . .
RUN npm run build
RUN npm test
CMD ["echo", "CI passed"]
# prod
FROM base AS prod
RUN npm ci --omit=dev
COPY --from=ci /app/dist ./dist
CMD ["node", "dist/server.js"]
Integración con GitHub Actions:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: docker build --target ci -t app-ci .
- run: docker run app-ci
Usar diferentes stages del mismo Dockerfile para DevContainers y CI/CD elimina estructuralmente los problemas de "diferencia de entornos." Si estás configurando un proyecto Next.js con Claude Code, este enfoque multi-stage es especialmente efectivo.
Preguntas Frecuentes
¿Claude Code funciona en Docker en Macs con ARM (M1/M2/M3)?
Sí. Docker Desktop para Apple Silicon ejecuta contenedores mediante Rosetta 2 o imágenes ARM nativas. Las imágenes node:22-bookworm-slim y node:22-alpine tienen variantes ARM64, así que Claude Code se instala y ejecuta sin problemas. El rendimiento es comparable a la ejecución nativa.
¿Puedo usar Claude Code con Docker Compose sin VS Code?
Por supuesto. DevContainers es solo una capa de conveniencia de VS Code. Puedes ejecutar docker compose up, luego docker exec -it <contenedor> bash, y lanzar claude directamente. Cualquier emulador de terminal funciona — VS Code no es necesario.
¿Cuánto espacio en disco necesita un DevContainer con Claude Code?
Una imagen de contenedor básica con Node.js + Claude Code ocupa unos 500MB. Añadir PostgreSQL y Redis lleva el total a unos 1.2GB. Los volúmenes nombrados para node_modules y datos de base de datos crecen con el tiempo. Cuenta con 2-3GB por proyecto para desarrollo cómodo.
¿Es seguro usar --dangerously-skip-permissions dentro de un contenedor?
Dentro de un contenedor correctamente configurado con reglas de firewall (como el devcontainer oficial), el riesgo se reduce significativamente. Claude Code solo puede acceder al sistema de archivos del contenedor y a destinos de red permitidos. Sin embargo, puede leer cualquier cosa montada en el contenedor — así que no montes directorios sensibles del host.
¿Puedo compartir la configuración DevContainer con mi equipo?
Sí — ese es uno de los principales beneficios. Haz commit del directorio .devcontainer/ en tu repositorio. Cada miembro del equipo que abra el proyecto en VS Code recibirá el prompt "Reopen in Container," y obtendrá un entorno idéntico. La configuración de Claude Code (CLAUDE.md) también viaja con el repo.
¿Cómo actualizo Claude Code dentro de un contenedor en ejecución?
Ejecuta npm update -g @anthropic-ai/claude-code dentro del contenedor. Para una actualización permanente, cambia la versión en tu Dockerfile y reconstruye: docker compose build --no-cache app.
¿Cuál es el overhead de rendimiento de ejecutar Claude Code en Docker vs nativamente?
En Linux y macOS, el overhead es insignificante — Docker usa el kernel del host directamente. En Windows con WSL2, hay un pequeño overhead por la capa de traducción WSL, pero las llamadas API de Claude Code (el cuello de botella) dependen de la red, no del CPU. En la práctica no notarás diferencia.
¿Puedo ejecutar múltiples instancias de Claude Code en contenedores separados simultáneamente?
Sí. Cada contenedor está completamente aislado, así que puedes ejecutar Claude Code en el contenedor A trabajando en una tarea de frontend mientras el contenedor B maneja un refactor de backend. Consulta nuestra guía sobre ejecución de múltiples instancias de Claude Code para patrones detallados.
Conclusión
Combinar Docker con Claude Code te da algo valioso: un entorno donde puedes hacer solicitudes audaces de forma segura.
- El aislamiento del contenedor limita el impacto de los cambios destructivos de Claude Code al contenedor mismo
- Las configuraciones DevContainer permiten que cada miembro del equipo ejecute Claude Code en entornos idénticos
- Configuraciones complejas de docker-compose pueden ser generadas por Claude Code en minutos
- El devcontainer oficial añade reglas de firewall para operación completamente desatendida
- Los usuarios de WSL2 obtienen los mismos beneficios siempre que los proyectos vivan en el sistema de archivos WSL2
Para empezar: crea un directorio .devcontainer/ y pídele a Claude Code que genere devcontainer.json y docker-compose.yml para tu proyecto. Tendrás un entorno de desarrollo equivalente a producción en quince minutos.
Si encuentras problemas, nuestra guía de solución de problemas de Claude Code cubre errores comunes relacionados con Docker. Y si buscas optimizar tu flujo de trabajo con Claude Code, la guía de reducción de costos de tokens muestra cómo mantener los costos de API bajo control incluso con desarrollo basado en contenedores.