Mejores prácticas de sandbox para Claude Code en ejecuciones sin supervisión

Las mejores prácticas de sandbox para Claude Code comienzan con una regla: si Claude Code puede editar archivos y ejecutar comandos sin que un humano apruebe cada paso, debe ejecutarse dentro de un espacio de trabajo aislado, no en un portátil o en un runner de IC compartido. Esto es aún más importante en el modo headless, porque el objetivo de una ejecución sin supervisión es que el agente pueda seguir adelante con ediciones de archivos, comandos de shell e instalaciones de dependencias sin esperar a que una persona haga clic en “permitir”. La guía de sandbox de Claude Code de Novita es la fuente de referencia para los comandos y banderas exactos de la plantilla. Este artículo se centra en lo que los equipos suelen necesitar después: por qué poner Claude Code en un sandbox en primer lugar, qué puede fallar si no se hace, y qué controles de producción añadir alrededor de la plantilla antes de integrarla en un flujo de trabajo real.

Por qué Claude Code necesita un sandbox en modo headless

Claude Code es útil porque hace más que redactar código. Lee archivos, edita archivos, ejecuta comandos de shell e itera tras ver la salida de las pruebas. Esa misma capacidad es la razón por la que necesita un sandbox cuando se pasa de una sesión interactiva de desarrollo a una automatización no supervisada.

En un terminal local, un humano suele detectar las malas ideas pronto. Ves el repositorio que abriste. Te das cuenta cuando un comando apunta al directorio equivocado. Puedes detener una instalación que parezca sospechosa. En un flujo de trabajo headless, esos puntos de control naturales desaparecen. El agente solo ve las instrucciones y el entorno que le diste.

Por eso la comparación correcta no es “Claude Code vs. sin Claude Code”. Es “Claude Code en una máquina real” vs. “Claude Code dentro de un límite de ejecución aislado”. Una vez que el agente puede actuar de forma autónoma, el espacio de trabajo pasa a formar parte del modelo de seguridad.

La superficie de riesgo es bastante concreta:

Área de riesgo	Qué puede salir mal sin un sandbox	Qué cambia un sandbox
Ámbito del repositorio	El agente edita el repositorio, la rama o los archivos locales no rastreados incorrectos	Cada tarea obtiene un checkout delimitado, un commit base conocido y una rama desechable
Ejecución de shell	Los comandos se ejecutan contra la máquina host o el runner compartido	Los comandos permanecen dentro de un sistema de archivos aislado y un límite de procesos
Instalación de dependencias	Las instalaciones de paquetes npm, pip u otros ejecutan scripts arbitrarios en el host	Las instalaciones de paquetes ocurren en un entorno desechable con políticas y registros
Secretos	Las variables de entorno visibles para el agente pueden incluir credenciales amplias de desarrollo o producción	Los secretos delimitados por tarea pueden limitarse a la sesión del sandbox
Revisión	El único registro es un resumen del chat o una transcripción del terminal	Se pueden capturar diff, registros, stdout, stderr y artefactos para su revisión

Si deseas una lista de verificación de diseño de sandbox más amplia que no sea específica de Claude, lee Sandbox para Agentes de Codificación: Cómo Ejecutar Código Generado por Agentes de Forma Segura y Ejecutar Claude Code o Agentes Gestionados en un Sandbox Aislado. La diferencia aquí es que Claude Code ya tiene un flujo de trabajo CLI concreto, por lo que la cuestión de infraestructura se vuelve más específica: ¿cómo ejecutar esa CLI de forma segura cuando no hay una persona supervisando?

Qué cambia al usar --dangerously-skip-permissions

Esta bandera es la razón por la que muchos equipos empiezan a preguntar sobre sandboxes. En el uso interactivo normal, Claude Code puede preguntar antes de editar archivos o ejecutar herramientas. En la automatización no supervisada, las indicaciones de aprobación interrumpen el flujo, por lo que los documentos de Novita muestran el patrón headless con claude --dangerously-skip-permissions -p "<prompt>" dentro de la plantilla claude-code.

Eso no significa que la bandera sea insegura por definición. Significa que la capa de seguridad se ha desplazado.

Cuando usas --dangerously-skip-permissions, debes asumir:

• Claude Code puede editar archivos inmediatamente.
• Claude Code puede ejecutar comandos inmediatamente.
• Claude Code puede continuar con una tarea de varios pasos sin pausar para revisión.

La respuesta correcta no es usar la bandera en una estación de trabajo real y esperar lo mejor. La respuesta correcta es usarla solo dentro de un sandbox donde el espacio de trabajo, el repositorio, los comandos, los secretos y la superficie de red ya estén restringidos. El límite del sandbox se convierte en el lugar donde reduces el radio de explosión.

Por eso también debes mantener la redacción precisa al documentar esta configuración. --dangerously-skip-permissions no es una recomendación para la comodidad en la máquina local. Es un patrón operativo exclusivo de sandbox para automatización headless. Si tu flujo de trabajo sigue apuntando Claude Code a un portátil de desarrollador, un bastión compartido o un runner similar a producción, has eliminado la indicación de aprobación humana sin añadir el control de infraestructura que debería reemplazarla.

Si tu equipo aún está decidiendo si confiar en las instalaciones de paquetes en ese entorno, combina este artículo con Cómo Permitir Instalaciones de Paquetes de Forma Segura en Sandboxes de Agentes de IA y Lista de Verificación de Límites de Aislamiento de Sandbox para Agentes de IA.

Cómo se asigna la plantilla claude-code de Novita a un flujo de trabajo de producción

La parte útil de los documentos de Novita es que no se quedan en lo abstracto. Muestran la mecánica real que necesita un flujo de trabajo de producción.

1. Modo headless -p y --print

Los documentos usan Claude Code en modo no interactivo -p para que la ejecución pueda aceptar un prompt, imprimir su resultado y salir. Eso importa porque la automatización headless necesita un contrato programático limpio. No quieres un terminal interactivo de larga duración adjunto a una sesión humana; quieres una ejecución orientada a tareas que pueda iniciarse, observarse y finalizarse.

Esta es la misma división que se discute en Documentación CLI de Claude Code: Claude Code interactivo es para un conductor humano, mientras que -p más salida estructurada es lo que hace que la CLI sea útil en scripts y pipelines de agentes.

2. Enrutamiento de modelos personalizado a través de ~/.claude/settings.json

Los documentos de Novita también muestran un detalle práctico que muchos equipos pasan por alto: escribir ~/.claude/settings.json dentro del sandbox para que Claude Code reciba su token de API, URL base y configuración del modelo a través del bloque env. Ese patrón importa por dos razones.

Primero, mantiene el tiempo de ejecución autocontenido. El sandbox puede arrancar con la configuración exacta orientada a Claude que la tarea necesita, en lugar de heredar lo que esté presente en la máquina de un desarrollador.

Segundo, admite un control explícito del entorno. Si tu flujo de trabajo usa Claude Code con un backend personalizado, la configuración del sandbox pasa a formar parte de la configuración revisada en lugar de un estado de shell personal oculto.

3. Clonación real de repositorios con credenciales delimitadas

Los documentos muestran sandbox.git.clone(...) con una ruta de destino, profundidad de clonación superficial y token de GitHub para repositorios privados. Esto no es una característica de conveniencia menor. Es la diferencia entre un espacio de trabajo de tarea reproducible y un agente trabajando en un directorio ambiguo.

Para uso en producción, el patrón más seguro es:

1. Clonar solo el repositorio necesario para la tarea.
2. Fijar la referencia o commit de inicio cuando tu flujo de trabajo requiera reproducibilidad.
3. Usar una rama de tarea para los cambios del agente.
4. Pasar credenciales Git delimitadas que puedan leer o escribir solo lo que la tarea necesita.

Si un repositorio aún no necesita acceso de escritura, no le des acceso de escritura solo porque el agente podría eventualmente abrir un PR.

4. Salida estructurada más session_id para trabajo multipaso

Los documentos muestran un segundo patrón útil: iniciar Claude Code con --output-format json, analizar el session_id devuelto, y luego continuar con --resume <session_id>. Esto es lo que convierte una edición de código de una sola vez en un flujo de trabajo multipaso que puedes gestionar programáticamente.

Este es el ajuste adecuado para tareas como:

• Paso 1: inspeccionar el repositorio y producir un plan de refactorización
• Paso 2: reanudar la misma sesión e implementar una parte
• Paso 3: reanudar de nuevo para ejecutar verificación o limpieza posterior

La mejor práctica importante no es “usar siempre resume”. Es “reanudar intencionalmente”. Si tu flujo de trabajo se beneficia de la continuidad, reanuda la misma sesión en el mismo sandbox. Si la tarea debe ser revisable de forma independiente, inicia un sandbox nuevo en lugar de arrastrar el estado implícitamente.

5. Eliminar el espacio de trabajo después de la tarea

Los documentos de Novita terminan los ejemplos eliminando el sandbox. Eso es exactamente el hábito que quieres en producción. Un agente de codificación headless no debería acumular silenciosamente espacios de trabajo obsoletos, procesos en segundo plano o credenciales persistentes. Un entorno desechable es más fácil de razonar que una máquina misteriosa con historial.

Si quieres una visión arquitectónica más amplia sobre ese modelo de ejecución, Construyendo un Agente de Codificación con el Sandbox de Agentes de Novita es la lectura complementaria adecuada.

Lista de verificación de mejores prácticas de sandbox para Claude Code

La siguiente lista de verificación es la versión de producción del flujo de trabajo de los documentos. Mantiene la mecánica exacta de la plantilla de Novita, y luego añade los controles que un pipeline automatizado suele necesitar.

• Un sandbox por tarea: No apuntes múltiples tareas no relacionadas a un entorno de Claude Code de larga duración. Los espacios de trabajo nuevos hacen que el estado inicial del repositorio sea evidente y facilitan la eliminación.
• Acceso Git delimitado: Si Claude Code solo necesita clonar e inspeccionar un repositorio, usa un token de solo lectura. Si debe enviar una rama, usa un token delimitado a ese repositorio y ese flujo de trabajo. Evita credenciales personales heredadas.
• Instalaciones de paquetes en sandbox: Claude Code a menudo necesita dependencias para reproducir una compilación o prueba fallida. Eso está bien, pero las instalaciones deben ocurrir dentro del sandbox con registros y políticas, no en la máquina del operador. Revisa los cambios en el archivo de bloqueo como cualquier otro cambio de código.
• Tratar la salida del shell como evidencia: Captura stdout, stderr, códigos de salida y los comandos que realmente se ejecutaron. Un resumen final del agente es útil, pero no es suficiente para la revisión por sí solo.
• Sin secretos de producción por defecto: Prefiere credenciales de corta duración o solo de staging. Un agente de codificación que puede leer el repositorio y ejecutar comandos no necesita tokens de administrador de nube amplios ni credenciales de base de datos de producción por defecto.
• Revisar el diff, no solo el resultado: El éxito headless solo significa que Claude Code completó el bucle que le diste. No significa que el cambio sea correcto o esté listo para enviar. Revisa los archivos modificados, los cambios de dependencias, la salida de comandos y cualquier artefacto generado.
• Mantener --dangerously-skip-permissions local al sandbox: Esta es la regla operativa más importante en la configuración. La bandera pertenece a un espacio de trabajo aislado y desechable. No debería ser tu atajo para ejecutar Claude Code no supervisado contra una máquina real.
• Separar la ejecución del lanzamiento: Claude Code puede tener permiso para inspeccionar, editar, probar y preparar un parche. Eso no significa que también deba poseer decisiones de fusión, publicación o despliegue. Mantén esas acciones detrás de un humano o una puerta de enlace de políticas explícita.
• Reanudar intencionalmente: Usa --resume <session_id> cuando la tarea se beneficie genuinamente de la continuidad. Reinicia el sandbox cuando necesites una prueba limpia de reproducibilidad o cuando una tarea no deba heredar el estado de otra tarea.
• Comparar la superficie completa del proveedor: Si estás eligiendo dónde alojar este flujo de trabajo, mira más allá de si el entorno puede lanzar Claude Code. Compara el ciclo de vida de la sesión, la ergonomía del repositorio, los registros, el comportamiento de pausa y reanudación, y las compensaciones operativas. Para ese ángulo, E2B vs. Daytona: Comparación de Sandbox para Agentes de IA y Novita Sandbox: Una Alternativa Rentable a E2B Pro con Compatibilidad Perfecta son las lecturas comparativas relevantes.

Errores comunes a evitar

Los errores más comunes con el sandbox de Claude Code son operativos, no conceptuales.

Error 1: Tratar el ejemplo de los documentos como una política de producción completa

Los documentos muestran cómo lanzar la plantilla claude-code correctamente. No pretenden ser tu política completa de revisión, red o gestión de secretos. Úsalos para la sintaxis y la mecánica de ejecución, luego añade tus propios límites de repositorio y aprobación.

Error 2: Reutilizar una estación de trabajo de desarrollador como el “sandbox”

Ejecutar Claude Code desde un terminal en tu portátil es un flujo de trabajo de desarrollo válido. No es lo mismo que un entorno desechable y aislado para automatización no supervisada.

Error 3: Dejar el estado de la sesión implícito

Si usas --resume, sabe qué estado estás arrastrando y por qué. Si la respuesta es “no estamos seguros, pero fue conveniente”, estás creando un problema de revisión más difícil.

Error 4: Mezclar secretos reales con trabajo de código exploratorio

Un sandbox está ahí para reducir el radio de explosión. Si el espacio de trabajo aún puede alcanzar sistemas de producción con credenciales amplias, has debilitado el límite más importante.

Error 5: Confiar en una ejecución exitosa más que en la evidencia

Un agente puede completar una tarea y aún así hacer el cambio incorrecto, tocar los archivos incorrectos o añadir una dependencia que no querías. Revisa el diff y los registros, no solo el resumen narrativo.

Preguntas frecuentes

¿Significa --dangerously-skip-permissions que Claude Code no tiene ninguna seguridad?

Significa que Claude Code ya no espera aprobaciones interactivas dentro de la sesión. La capa de seguridad prevista en un flujo de trabajo headless es el límite del sandbox alrededor de la sesión: repositorio aislado, credenciales limitadas, ejecución de comandos dentro del sandbox, registros capturados y revisión humana antes de la fusión.

¿Debería cada automatización de Claude Code ejecutarse en un sandbox nuevo?

Los sandboxes nuevos son el valor predeterminado más limpio para tareas independientes. Los flujos de trabajo basados en reanudación son útiles cuando la misma tarea de varios pasos necesita continuidad, pero el estado debe ser deliberado y revisable, no accidental.

¿Puede Claude Code instalar paquetes de forma segura en un sandbox?

Se puede hacer más seguro, pero no automáticamente seguro. Usa políticas de paquetes, revisión de archivos de bloqueo, acceso de red delimitado y registros de auditoría. Las instalaciones de paquetes son uno de los pasos de mayor riesgo en un flujo de trabajo de codificación no supervisado.

¿Es suficiente la página de documentos de Novita para implementar el flujo de trabajo?

Es suficiente para la sintaxis de la plantilla publicada y la mecánica de Claude Code admitida: ejecuciones headless, configuración de settings.json, sandbox.git.clone, salida JSON y reanudación de sesión. Para el despliegue en producción, aún necesitas tus propias decisiones de revisión, credenciales y políticas alrededor de ese tiempo de ejecución.

Artículos recomendados

• Ejecutar Claude Code o Agentes Gestionados en un Sandbox Aislado
• Sandbox para Agentes de Codificación: Cómo Ejecutar Código Generado por Agentes de Forma Segura
• Construyendo un Agente de Codificación con el Sandbox de Agentes de Novita