Claude Code en un devcontainer

Un entorno de desarrollo en sandbox para ejecutar Claude Code con bypassPermissions habilitado de forma segura. Creado en Trail of Bits para flujos de trabajo de auditoría de seguridad.

¿Por qué usar esto?

Ejecutar Claude con bypassPermissions en tu máquina host es arriesgado: puede ejecutar cualquier comando sin confirmación. Este devcontainer proporciona aislamiento del sistema de archivos, de modo que obtienes los beneficios de productividad de un Claude sin restricciones sin arriesgar tu sistema host.

Diseñado para:

• Auditorías de seguridad: Revisar código de clientes sin arriesgar tu host
• Repositorios no confiables: Explorar bases de código desconocidas de forma segura
• Trabajo experimental: Deja que Claude modifique código libremente de forma aislada
• Proyectos con múltiples repos: Trabaja en varios repositorios relacionados

Requisitos previos

• Runtime de Docker (uno de):

  • Docker Desktop - asegúrate de que esté en ejecución
  • OrbStack
  • Colima: brew install colima docker && colima start

• Para flujos de trabajo en terminal (instalación única):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

Inicio rápido

Elige el patrón que se adapte a tu flujo de trabajo:

Patrón A: Contenedor por proyecto (aislado)

Cada proyecto tiene su propio contenedor con volúmenes independientes. Ideal para revisiones puntuales, repos no confiables o cuando necesitas aislamiento entre proyectos.

Terminal:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor:

1. Instala la extensión Dev Containers:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. Configura el devcontainer (elige una opción):

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Abre la carpeta de tu proyecto en VS Code y luego:

   • Presiona Cmd+Shift+P (Mac) o Ctrl+Shift+P (Windows/Linux)
   • Escribe "Reopen in Container" y selecciona Dev Containers: Reopen in Container

Patrón B: Contenedor de espacio de trabajo compartido (agrupado)

Un directorio principal contiene la configuración del devcontainer y clonas varios repos dentro. Volúmenes compartidos entre todos los repos. Ideal para proyectos de clientes, repositorios relacionados o trabajo continuo.

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

Autenticación por token (headless)

Para servidores headless o para omitir el asistente de inicio de sesión interactivo:

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

El token se reenvía al contenedor. En cada creación de contenedor, post_install.py ejecuta un handshake de autenticación de una sola vez para que claude se inicie sin el asistente de inicio de sesión.

Esto evita que el asistente interactivo de incorporación de Claude Code aparezca siempre en los contenedores, incluso con credenciales válidas (#8938).

Si no configuras un token, el flujo de inicio de sesión interactivo funciona como antes.

Comandos auxiliares de CLI

devc .              Install template + start container in current directory
devc up             Start the devcontainer
devc rebuild        Rebuild container (preserves persistent volumes)
devc destroy [-f]   Remove container, volumes, and image for current project
devc down           Stop the container
devc shell          Open zsh shell in container
devc exec CMD       Execute command inside the container
devc upgrade        Upgrade Claude Code in the container
devc mount SRC DST  Add a bind mount (host → container)
devc sync [NAME]    Sync Claude Code sessions from devcontainers to host
devc template DIR   Copy devcontainer files to directory
devc self-install   Install devc to ~/.local/bin

Nota: Usa devc destroy para limpiar los recursos de Docker de un proyecto. Eliminar contenedores manualmente (por ejemplo, docker rm) dejará volúmenes e imágenes huérfanos que devc destroy no podrá encontrar.

Sincronización de sesiones para /insights

El comando /insights de Claude Code analiza el historial de tus sesiones, pero solo lee desde ~/.claude/projects/ en el host. Las sesiones dentro de los volúmenes del devcontainer son invisibles para él.

devc sync copia los registros de sesión de todos los devcontainers (en ejecución y detenidos) al host para que /insights pueda incluirlos:

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

Los devcontainers se descubren automáticamente mediante etiquetas de Docker: no es necesario conocer los nombres o IDs de los contenedores. La sincronización es incremental, por lo que es seguro ejecutarla repetidamente.

Compartir archivos

VS Code / Cursor

Arrastra archivos desde tu host al panel del Explorador de VS Code: se copian automáticamente en /workspace/. No se necesita configuración.

Terminal: devc mount

Para que un directorio del host esté disponible dentro del contenedor:

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

Esto añade un bind mount a devcontainer.json y recrea el contenedor. Los montajes existentes se conservan al actualizar devc template.

Consejo: Una "carpeta de intercambio" compartida es útil para pasar archivos sin montar todo tu directorio personal.

Nota de seguridad: Evita montar directorios grandes del host (por ejemplo, $HOME). Cada ruta montada es escribible desde dentro del contenedor a menos que se especifique --readonly, lo que socava el aislamiento del sistema de archivos que proporciona este proyecto.

Aislamiento de red

Por defecto, los contenedores tienen acceso de red saliente completo. Para una seguridad más estricta, usa iptables para restringir el acceso a la red.

Cuándo habilitar el aislamiento de red

• Revisar código que pueda contener dependencias maliciosas
• Auditar software con telemetría o comportamiento de phone-home
• Aislamiento máximo para revisiones altamente sensibles

Ejemplo: Claude + GitHub + registros de paquetes

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

Compensaciones

• Bloquea los gestores de paquetes a menos que permitas registros en la lista de permitidos
• Puede romper herramientas que requieren acceso a la red
• La resolución de DNS sigue funcionando (considera bloquearla si eres paranoico)

Modelo de amenazas

La amenaza principal que aborda este proyecto es que Claude Code ejecute comandos arbitrarios en tu máquina host. Cuando bypassPermissions está habilitado, Claude ejecuta comandos de shell, instala paquetes y modifica archivos sin confirmación. En una máquina host, esto significa que puede modificar tu configuración de shell, ejecutar rm -rf fuera del directorio del proyecto o abusar de las credenciales almacenadas localmente. El devcontainer confina todo eso a un contenedor desechable donde el radio de explosión se limita a /workspace.

El contenedor incluye herramientas de desarrollo comunes para que puedas hacer todo el trabajo de desarrollo dentro de él, no solo ejecutar Claude. El flujo de trabajo previsto es: clonar un repositorio, iniciar el devcontainer y trabajar enteramente dentro de él. Si tu proyecto necesita runtimes o herramientas adicionales más allá de los incluidos, agrégalos al Dockerfile para un uso repetido o instálalos ad-hoc con devc exec.

Para conocer los límites específicos de lo que está y no está aislado, consulta Modelo de seguridad a continuación. Un matiz que vale la pena señalar: el runtime del devcontainer reenvía automáticamente el socket del agente SSH del host (SSH_AUTH_SOCK) al contenedor. Esto permite que el código dentro del contenedor se autentique como tú a través de SSH (por ejemplo, git push), pero el material de la clave privada permanece en el host y nunca se expone al contenedor.

Modelo de seguridad

Este devcontainer proporciona aislamiento del sistema de archivos, pero no un sandbox completo.

En sandbox: Sistema de archivos (archivos del host inaccesibles), procesos (aislados del host), instalaciones de paquetes (permanecen en el contenedor)

No en sandbox: Red (salida completa por defecto; consulta Aislamiento de red), identidad de git (~/.gitconfig montado de solo lectura), agente SSH (socket reenviado, las claves permanecen en el host), socket de Docker (no montado por defecto)

El contenedor configura automáticamente el modo bypassPermissions: Claude ejecuta comandos sin confirmación. Esto sería arriesgado en una máquina host, pero el contenedor en sí es el sandbox.

Detalles del contenedor

Los volúmenes se almacenan fuera del contenedor, por lo que el historial de tu shell, la configuración de Claude y el inicio de sesión de gh persisten incluso después de devc rebuild. El ~/.gitconfig del host se monta de solo lectura para la identidad de git.

Solución de problemas

"devcontainer CLI not found"

npm install -g @devcontainers/cli

El contenedor no se inicia

1. Comprueba que Docker esté en ejecución
2. Intenta reconstruir: devc rebuild
3. Revisa los registros: docker logs $(docker ps -lq)

La autenticación de GitHub CLI no persiste

El volumen de gh puede necesitar una corrección de propiedad:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv no funciona

Python se gestiona mediante uv:

uv run script.py              # Run a script
uv add package                # Add project dependency
uv run --with requests py.py  # Ad-hoc dependency

Desarrollo

Compila la imagen manualmente:

devcontainer build --workspace-folder .

Prueba el contenedor:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh