Claude Code en un dev container: la configuración segura y reproducible
Instala la extensión Dev Containers, mantén Docker en marcha, añade la feature oficial de claude-code, Reopen in Container, inicia sesión desde la terminal y mantén la autenticación viva entre rebuilds — cada paso verificado contra la documentación de dev containers de Anthropic.
TL;DR
- Instala la extensión Dev Containers, mantén Docker en marcha y luego Reopen in Container en cualquier repo con .devcontainer/ — Claude Code y cada comando que ejecuta corren dentro del contenedor, no en tu máquina.
- La feature oficial — "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" en el bloque features — instala la CLI en cualquier devcontainer; VS Code recibe además la extensión y ambos comparten un mismo ~/.claude.
- Inicia sesión desde la terminal del contenedor; si el callback del navegador no la alcanza, pega el código en el prompt. Haz que la autenticación sobreviva a los rebuilds con un volumen en ~/.claude más containerEnv.CLAUDE_CONFIG_DIR.
- Un dev container reemplaza el entorno (el /sandbox en cambio confina comandos individuales en tu máquina). Se combinan — contenedor para el entorno, sandbox y avisos de permisos para el comportamiento.
Run Your AI Coding Agent in Dev Containers - Complete Beginner's Guide
Canal: Visual Studio Code15:39
Step-by-Step: Run Claude Code SAFELY in a Dev Container
Canal: Fuzz Puppy6:56
Development containers — official documentation
Documentación oficial: code.claude.com/docs
Cada paso de configuración, nombre de feature y ruta de credenciales de esta página está verificado contra la documentación oficial de development containers; los videos de arriba son la fuente visual y de hechos.
Las capturas se atribuyen a sus creadores con enlaces profundos a los minutos exactos. No se usan fotogramas con caras.
Ejecuta Claude Code en un dev container, paso a paso
Parte 1 — Requisitos: VS Code se encuentra con Docker
- 1
Instala la extensión Dev Containers
Abre la vista de extensiones en VS Code e instala Dev Containers de Microsoft. Esta extensión añade el indicador remoto en la barra de estado, el comando Reopen in Container y el Remote Explorer — todo el flujo de abajo pasa por ella. Todavía no hace falta Docker.
La extensión Dev Containers es la que añade Reopen in Container a VS Code — instálala primero desde la vista de extensiones.Ver en 2:00 - 2
Instala Docker Desktop y arráncalo
Los dev containers son contenedores reales, así que un motor de contenedores debe estar corriendo antes de que se abra nada. Docker Desktop es la opción habitual en macOS y Windows; Docker Engine funciona en Linux. Arráncalo y déjalo corriendo — un motor apagado es la causa número uno de un "Opening Remote" atascado en el primer intento.
Docker Desktop solo necesita estar corriendo; una lista de contenedores vacía es exactamente el aspecto de una configuración sana previa al contenedor.Ver en 2:12 - 3
Sabe qué cambia para Claude Code
Tras Reopen in Container, VS Code ejecuta su servidor dentro del contenedor — y también cada comando que ejecuta Claude Code. Las instalaciones, las ejecuciones de tests y las ediciones de archivos se quedan dentro del contenedor mientras la carpeta del workspace se monta de vuelta en tu repo. Tu máquina solo necesita VS Code y Docker; los toolchains y las dependencias viven en la imagen, y un experimento fugado del agente no puede tocar nada de fuera.
Parte 2 — Un contenedor funcional, de punta a punta
- 4
Abre un dev container listo para usar
La forma más rápida de ver la maquinaria funcionar: en el Remote Explorer, elige un ejemplo como el dev container de Go. VS Code clona github.com/microsoft/vscode-remote-try-go y lo abre dentro de un volumen de contenedor — sin configuración escrita por ti todavía.
El Remote Explorer trae ejemplos listos — elige uno y VS Code clona el repo directo a un volumen de contenedor.Ver en 2:30 - 5
Deja que VS Code construya y conecte
La primera conexión clona el repo, descarga la imagen del contenedor capa por capa y arranca el contenedor — la barra de estado avisa "Connecting to Dev Container". Con una conexión lenta esta es la espera más larga de la configuración; cada apertura posterior reutiliza la imagen y tarda segundos.
La primera build descarga la imagen del contenedor capa por capa; la barra de estado sigue la conexión al dev container.Ver en 2:52 - 6
Confirma que la terminal está dentro del contenedor
Abre una terminal nueva e imprime la versión del toolchain (aquí go version). La salida nombra el SO y la arquitectura del contenedor, no los de tu portátil. Esta terminal es exactamente donde lanzarías claude — y todo lo que ejecute se queda dentro del contenedor.
go version imprime el toolchain del contenedor, no el de tu portátil — ejecuta claude en esta terminal y también se quedará dentro.Ver en 3:50 - 7
Lee el devcontainer.json
El archivo .devcontainer/devcontainer.json define todo el entorno: la imagen base (o un Dockerfile), las extensiones de VS Code que instalar en el contenedor, los puertos reenviados, los pasos de postCreateCommand y el remoteUser. Para Claude Code este archivo es también donde van la feature oficial y el volumen de credenciales — cubierto en los pasos 9 y 13.
Todo lo que construye el contenedor vive en .devcontainer/devcontainer.json: imagen, extensiones, puertos reenviados, comandos post-create.Ver en 4:40 - 8
Apunta al agente hacia el workspace
Adjunta @workspace en el panel del agente y pídele que explique el proyecto. La explicación y cada comando detrás de ella se ejecutan dentro del contenedor. Claude Code funciona igual una vez que su CLI está instalada en la imagen: contexto al estilo @workspace más comandos que nunca salen del contenedor.
Pidiéndole al agente que explique el proyecto vía @workspace — cada comando que ejecuta corre dentro del contenedor.Ver en 5:20 - 9
Cambia a la feature oficial de Claude Code
Sin instalaciones manuales: añade "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" al bloque features de devcontainer.json y reconstruye. La feature instala la CLI — y, cuando el contenedor se abre en VS Code, también la extensión de Claude Code, compartiendo el mismo ~/.claude que la terminal. Si la imagen base no tiene Node.js verás "Failed to install Node.js and npm": añade la feature de Node por encima. Los ajustes de entorno como CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC o DISABLE_AUTOUPDATER van bajo containerEnv, y los mounts pueden traer tus otros repos locales al contenedor.
- 10
Ejecuta la app y usa el puerto reenviado
Arranca la app desde dentro del contenedor (panel de depuración, npm run dev, go run — lo que pida el stack) y VS Code detecta el puerto a la escucha: una notificación ofrece abrirlo en tu navegador local. El servidor nunca sale del contenedor; el reenvío solo hace que localhost se comporte como siempre.
La app corre en el puerto 9000 dentro del contenedor; VS Code lo reenvía para que localhost funcione exactamente como siempre.Ver en 6:08
Parte 3 — Tu propio repo y el inicio de sesión
- 11
Añade un dev container a tu propio proyecto
En cualquier repo, ejecuta Dev Containers: Add Dev Container Configuration Files desde la paleta de comandos o el indicador remoto y elige "Add configuration to workspace folder". Confirmada junto al código, la configuración da a tus compañeros — y a Codespaces — el mismo entorno gratis.
¿Todavía sin devcontainer.json? VS Code genera uno desde una plantilla — déjalo en el workspace para que git lo comparta.Ver en 9:00 - 12
Elige la plantilla y las features
VS Code sugiere una plantilla que encaja con tu stack (Node.js, Python, Go…) y luego muestra la lista de features — instaladores reutilizables como Git LFS o la GitHub CLI. En esa misma lista encaja la feature claude-code del paso 9. Acepta los valores por defecto (o deja que el agente refine el archivo generado) y reabre en contenedor.
En la lista de features es donde encaja una línea de feature de Claude Code junto a lo que sugiera la plantilla.Ver en 9:48 - 13
Inicia sesión dentro del contenedor
Ejecuta claude en la terminal integrada y elige tu inicio de sesión (suscripción de Claude o Anthropic Console). El navegador se abre en tu host; si el callback no alcanza el contenedor, copia el código del navegador y pégalo en el prompt "Paste code here if prompted". Para sobrevivir a los rebuilds, monta un volumen en ~/.claude y define containerEnv.CLAUDE_CONFIG_DIR con la misma ruta — el archivo de cuenta ~/.claude.json vive fuera de esa carpeta, por eso importan las dos mitades. Para ejecuciones headless o Codespaces, genera un token con claude setup-token y pasa ANTHROPIC_API_KEY o CLAUDE_CODE_OAUTH_TOKEN.
Dev container vs /sandbox: ¿qué aislamiento necesitas?
Claude Code trae dos respuestas de aislamiento y resuelven problemas distintos. Un dev container reemplaza el entorno en el que trabaja el agente; el sandbox integrado confina los comandos que ejecuta en tu máquina actual. La documentación oficial los posiciona como complementarios — el devcontainer de referencia hasta incluye un script de restricción de tráfico saliente.
- 1Alcance. Un dev container cambia todo el entorno — SO, toolchain, dependencias — por el definido en devcontainer.json. El sandboxing conserva tu máquina y restringe lo que cada comando bash puede leer, escribir y alcanzar en la red.
- 2Requisitos. Los dev containers necesitan Docker (Desktop o Engine) más la extensión Dev Containers; el sandboxing viene integrado en Claude Code y no necesita ninguno.
- 3Mecánica de equipo. devcontainer.json se sube al repositorio, así que cada compañero y cada Codespace construyen el entorno idéntico; la política del sandbox vive en los ajustes de Claude Code y sigue al usuario, no al repo.
- 4Radio de impacto. En un contenedor, un rm -rf desastroso o una instalación maliciosa golpean un sistema de archivos desechable y tu host queda intacto. El sandbox apunta al mismo resultado por comando — sin frontera de contenedor.
- 5Elige un dev container cuando el proyecto en sí necesita un entorno: múltiples runtimes, onboarding limpio, desarrollo en la nube. Elige el sandbox como barandilla diaria para sesiones en tu host. Se combinan — ejecuta Claude Code dentro de un dev container y mantén el sandboxing y los avisos de permisos activados.
Una línea más los diferencia: /sandbox es una política por sesión que puedes ajustar a mitad de conversación, mientras que un dev container se decide antes de que la sesión empiece — cambiarlo supone un rebuild. Las ejecuciones por lotes desatendidas se apoyan en ambos a la vez: usuario de contenedor sin root, tráfico saliente restringido y --dangerously-skip-permissions solo dentro del contenedor.
¿Algo no se comporta? Empieza aquí
La mayoría de fricciones del dev container con Claude Code caen en un puñado de patrones conocidos. Cada arreglo de abajo viene directamente de la documentación oficial de development containers.
- 1"Failed to install Node.js and npm" durante la instalación de la feature: la imagen base no tiene Node.js. Añade la feature de Node (ghcr.io/devcontainers/features/node:1) por encima de la de claude-code en el bloque features y reconstruye.
- 2El inicio de sesión se completa en el navegador pero el contenedor sigue deslogueado: el callback de OAuth no alcanza el contenedor. Copia el código que muestra el navegador y pégalo en el prompt "Paste code here if prompted" de la terminal.
- 3El login y los ajustes desaparecen tras cada rebuild: nada persiste ~/.claude. Monta un volumen nombrado en esa ruta y define containerEnv.CLAUDE_CONFIG_DIR con ella — incluye la variable devcontainerId en el nombre del volumen para que los proyectos sigan aislados. En Codespaces la carpeta sobrevive a stop/start pero se limpia en un rebuild completo, así que provee ANTHROPIC_API_KEY o un CLAUDE_CODE_OAUTH_TOKEN de claude setup-token como secreto.
- 4Sorpresas de versión de Claude Code: el tag claude-code:1.0 de la feature fija la versión del script de instalación, no la de la CLI — se instala la última release y se autoactualiza dentro del contenedor. Para congelar una versión, instálala en el Dockerfile con npm install -g @anthropic-ai/claude-code@X.Y.Z.
- 5"Is Docker running?" o un "Opening remote" atascado: el motor no responde — arranca Docker Desktop (o el daemon) y reintenta. Si --dangerously-skip-permissions se niega a arrancar, el contenedor corre como root; define remoteUser con un usuario sin root como "vscode". Las organizaciones pueden desactivar el modo bypass por completo vía managed-settings.json en /etc/claude-code.
Reconstruir es el reintento universal: paleta de comandos → "Dev Containers: Rebuild Container" vuelve a leer devcontainer.json y re-ejecuta las features tras cualquier edición. Si un rebuild se comporta distinto a un clon fresco, borra el contenedor y reabre — las imágenes y los volúmenes nombrados sobreviven al borrado.