Devcontainer en sandbox para ejecutar Claude Code en modo bypass de forma segura. Diseñado para auditorías de seguridad y revisión de código no confiable.
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.
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:
Runtime de Docker (uno de):
brew install colima docker && colima startPara 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
Los valores predeterminados de Colima (QEMU + sshfs) son conservadores. Para un mejor rendimiento:
# 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
Ajusta --cpu y --memory según tu Mac (por ejemplo, 6/16 para Pro, 8/32 para Max).
| Opción | Beneficio |
|---|---|
--vm-type vz | Apple Virtualization.framework (más rápido que QEMU) |
--mount-type virtiofs | E/S de archivos 5-10 veces más rápida que sshfs |
--vz-rosetta | Ejecutar contenedores x86 mediante Rosetta |
Verifica con colima status - debería mostrar "macOS Virtualization.Framework" y "virtiofs".
Elige el patrón que se adapte a tu flujo de trabajo:
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:
Instala la extensión Dev Containers:
ms-vscode-remote.remote-containersanysphere.remote-containersConfigura 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/
Abre la carpeta de tu proyecto en VS Code y luego:
Cmd+Shift+P (Mac) o Ctrl+Shift+P (Windows/Linux)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
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.
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 destroypara limpiar los recursos de Docker de un proyecto. Eliminar contenedores manualmente (por ejemplo,docker rm) dejará volúmenes e imágenes huérfanos quedevc destroyno podrá encontrar.
/insightsEl 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.
Arrastra archivos desde tu host al panel del Explorador de VS Code: se copian automáticamente en /workspace/. No se necesita configuración.
devc mountPara 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.
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.
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
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.
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.
| Componente | Detalles |
|---|---|
| Base | Ubuntu 24.04, Node.js 22, Python 3.13 + uv, zsh |
| Usuario | vscode (sudo sin contraseña), directorio de trabajo /workspace |
| Herramientas | rg, fd, tmux, fzf, delta, iptables, ipset |
| Volúmenes (sobreviven a rebuilds) | Historial de comandos (/commandhistory), configuración de Claude (~/.claude), autenticación de GitHub CLI (~/.config/gh) |
| Montajes del host | ~/.gitconfig (solo lectura), .devcontainer/ (solo lectura) |
| Configuración automática | Habilidades de anthropics + trailofbits, git-delta |
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.
npm install -g @devcontainers/cli
devc rebuilddocker logs $(docker ps -lq)El volumen de gh puede necesitar una corrección de propiedad:
sudo chown -R $(id -u):$(id -g) ~/.config/gh
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
Compila la imagen manualmente:
devcontainer build --workspace-folder .
Prueba el contenedor:
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh