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):

  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):

   # 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