Ejecutar Claude Code o Agentes Administrados en un Sandbox Aislado

Ejecuta agentes de codificación al estilo Claude Code o administrados en un sandbox asignando a cada agente un espacio de trabajo con alcance definido, permisos explícitos sobre archivos, ejecución de shell controlada, una política de red y paquetes, límites claros para secretos, registros duraderos, artefactos capturados y revisión humana antes de que los cambios se fusionen o desplieguen. El agente aún puede leer código, editar archivos, instalar dependencias, ejecutar pruebas y producir un parche, pero el entorno que lo rodea decide qué puede tocar, qué puede obtener, qué credenciales puede ver y cuándo una persona debe aprobar el siguiente paso.

Qué necesita ser aislado

Un agente de codificación no es solo un chatbot conectado a un repositorio. Una vez que puede editar archivos y ejecutar comandos, comienza a parecerse a un trabajador de compilación junior con razonamiento de modelo de lenguaje en el bucle. Ese trabajador puede ejecutar npm test, inspeccionar archivos generados, iniciar un servidor de desarrollo o intentar instalar un paquete porque un mensaje de error lo sugiere. Si el espacio de trabajo es tu portátil, un ejecutor de CI compartido o una máquina virtual de larga duración similar a producción, el radio de explosión es demasiado amplio.

El objetivo de aislamiento es todo el bucle de trabajo del agente:

• La copia del repositorio y la rama que el agente puede leer o modificar.
• Las rutas del sistema de archivos que el agente puede escribir.
• Los comandos que puede ejecutar automáticamente.
• Los comandos que requieren aprobación.
• Los registros de paquetes, dominios y API a los que puede acceder.
• Las credenciales expuestas a la sesión.
• Los registros, diferencias, salidas de pruebas, capturas de pantalla y artefactos conservados para revisión.
• El comportamiento de limpieza después de éxito, fallo o tiempo de espera.

Claude Code y otros productos de agentes de codificación administrados pueden incluir sus propios sistemas de permisos. La documentación de Claude Code de Anthropic, por ejemplo, describe configuraciones de permisos para herramientas permitidas y denegadas, comportamiento de aprobación y orientación sobre sandboxing para uso local. Trata esos controles como una capa, no como el límite completo. Un diseño más sólido coloca al agente dentro de un tiempo de ejecución aislado y luego aplica permisos de herramientas dentro de ese tiempo de ejecución.

Arquitectura de referencia

Un flujo de trabajo práctico de agente en sandbox tiene cuatro capas:

Capa	Propósito	Control típico
Controlador del agente	Decide el plan de tareas y las llamadas a herramientas	Permisos de modelo/herramienta, modo de aprobación, prompt de tarea
Entorno de ejecución del sandbox	Aloja el espacio de trabajo donde se ejecutan los comandos	Sistema de archivos aislado, límites de proceso, controles de ciclo de vida
Puerta de enlace de políticas	Decide qué acciones están permitidas	Reglas de comandos, reglas de salida de red, política de paquetes, alcance de secretos
Superficie de revisión	Permite que los humanos inspeccionen los resultados	Diff, registros, resultados de pruebas, artefactos, solicitud de extracción

Mantén estas capas separadas. Si el controlador del agente se ve comprometido por inyección de prompt, el entorno de ejecución del sandbox y la puerta de enlace de políticas aún deberían limitar lo que sucede. Si una instalación de paquete extrae código inesperado, la red y los registros de artefactos deberían hacerlo visible. Si el agente produce un parche plausible, la superficie de revisión debería mostrar exactamente qué cambió y qué pruebas se ejecutaron.

Un objeto de política conceptual podría verse así:

workspace:
  mode: ephemeral
  repo_ref: pull-request-branch
  writable_paths:
    - /workspace/project
  readonly_paths:
    - /workspace/reference
commands:
  auto_allow:
    - git status
    - npm test
    - npm run lint
    - pytest
  require_approval:
    - npm install
    - pip install
    - docker build
    - git push
  deny:
    - rm -rf /
    - curl ... | sh
network:
  default: deny
  allow:
    - registry.npmjs.org
    - pypi.org
    - files.pythonhosted.org
secrets:
  expose:
    - READ_ONLY_PACKAGE_TOKEN
  deny:
    - PRODUCTION_DATABASE_URL
    - CLOUD_ADMIN_TOKEN
artifacts:
  capture:
    - git diff
    - test-results/
    - screenshots/
    - command-log.jsonl

Esto no es intencionadamente un ejemplo de SDK. El formato exacto de la política depende de tu framework de agente y proveedor de sandbox. El punto importante es que los permisos deben expresarse fuera del razonamiento de forma libre del modelo y luego ser aplicados por el tiempo de ejecución o la capa de orquestación.

Configuración del espacio de trabajo y el repositorio

Comienza cada ejecución del agente desde un espacio de trabajo limpio. Un agente administrado no debe heredar el historial de shell de un desarrollador, el agente SSH, los dotfiles, el inicio de sesión de CLI en la nube ni los archivos locales no rastreados a menos que haya una razón deliberada.

Para el trabajo con repositorios, utiliza una copia dedicada:

• Clona o monta solo el repositorio necesario para la tarea.
• Crea una nueva rama de tarea en lugar de editar la rama predeterminada.
• Fija el commit base para que la revisión pueda reproducir el punto de partida.
• Mantén los cachés de dependencias separados de las rutas de origen modificables.
• Almacena los artefactos generados fuera del árbol de origen a menos que formen parte del diff previsto.

El aislamiento de ramas es importante porque los agentes de codificación a menudo prueban varios enfoques antes de decidirse por uno. Una rama de tarea limpia proporciona a los revisores un diff normal de solicitud de extracción en lugar de un espacio de trabajo mixto que contiene experimentos temporales. Si el agente necesita comparar con una implementación de referencia, monta esa referencia como solo lectura.

Para agentes administrados de larga duración, decide si el sandbox es efímero, se pausa o se captura en instantánea. Los espacios de trabajo efímeros son más fáciles de razonar. Las instantáneas y la pausa/reanudación son útiles para trabajos largos, sesiones de navegador y pasos de configuración costosos, pero aún así deben preservar un rastro de auditoría claro: cuándo se creó la instantánea, qué archivos estaban presentes y qué credenciales estaban disponibles.

Permisos del sistema de archivos

El alcance del sistema de archivos debe ser más estrecho que “el agente puede leer toda la máquina”. La mayoría de las tareas de codificación necesitan:

• Acceso de lectura/escritura al espacio de trabajo del repositorio.
• Acceso de solo lectura a contextos de tarea seleccionados, fixtures o documentación.
• Un directorio temporal para archivos de compilación y archivos temporales.
• Sin acceso a los directorios de inicio del host, repositorios no relacionados, credenciales en la nube, perfiles de navegador o volcados de datos de producción.

Los permisos de escritura merecen especial atención. Un agente de codificación que puede editar un repositorio también puede editar scripts, pruebas, lockfiles, configuración de CI y archivos de despliegue. Eso puede ser exactamente lo que requiere la tarea, pero debería ser visible en la revisión. Para rutas sensibles, como .github/workflows/, manifiestos de despliegue o configuración de publicación de paquetes, requiere un paso de aprobación más fuerte o una revisión final propiedad de un humano.

Utiliza listas blancas de archivos cuando la tarea sea estrecha. Por ejemplo, un agente de documentación puede necesitar solo docs/ y un directorio de vista previa generado. Un agente de actualización de dependencias puede necesitar package.json, lockfiles y snapshots de pruebas. Una refactorización amplia necesita acceso más amplio, pero la revisión debería entonces esperar un diff más grande y pruebas más completas.

Política de ejecución de shell

El acceso al shell es donde los agentes de codificación se vuelven útiles y arriesgados. Necesitan ejecución de comandos para ejecutar pruebas, formatear código, inspeccionar errores de compilación y verificar correcciones. No necesitan autoridad sin restricciones para ejecutar cualquier comando sin pausa.

Una buena política de shell tiene tres categorías:

Categoría	Ejemplos	Por qué es importante
Permitido automáticamente	git status, npm test, pytest, go test ./..., npm run lint	Mantiene rápidos los bucles normales de edición-prueba
Requiere aprobación	instalaciones de paquetes, migraciones, servicios de larga duración, CLIs externos, git push	Añade fricción donde cambia el estado, el costo o el riesgo de red
Denegado	comandos destructivos del host, volcado de credenciales, piping de shell inseguro, escrituras fuera del espacio de trabajo	Bloquea acciones que no deberían delegarse

No confíes solo en la coincidencia de texto de comandos. Los agentes pueden ejecutar comandos a través de scripts, hooks de gestores de paquetes o shells anidados. Para entornos de mayor riesgo, combina la política de comandos con límites del sistema de archivos a nivel de ejecución, límites de recursos y controles de red.

Los comandos de larga duración necesitan comportamiento de tiempo de espera. Un servidor de pruebas, una automatización de navegador o un observador de compilación pueden permanecer activos después de que el agente haya seguido adelante. Captura IDs de proceso, stdout, stderr, estado de salida, tiempo de ejecución y motivo de terminación. Si un comando abre un puerto de vista previa, registra el mapeo de puertos y ciérralo durante la limpieza.

Instalaciones de paquetes y salida de red

La instalación de paquetes es una de las características más útiles de un espacio de trabajo de agente y uno de los lugares más fáciles para que entre el riesgo. Un agente de codificación puede instalar un paquete porque una respuesta de Stack Overflow, un README o un plan generado por el modelo lo sugirió. Eso puede cambiar el gráfico de dependencias, ejecutar scripts de instalación y alcanzar registros externos.

Para guías de implementación y flujos de trabajo de producción, comienza con una postura de red de denegación predeterminada, luego permite lo que la tarea necesita:

• Registros de paquetes como npm o PyPI, preferiblemente a través de un espejo o caché de registro.
• Hosts de origen necesarios para el repositorio y submódulos.
• Dominios de documentación necesarios para la tarea.
• APIs internas solo cuando el sandbox tenga la clasificación de datos adecuada.

Evita dar a cada agente acceso amplio a Internet de salida por defecto. Si se requiere acceso amplio para investigación o automatización de navegador, separa esa ejecución de las ejecuciones de modificación de código y etiqueta el artefacto en consecuencia.

Para instalaciones de paquetes, registra:

• El comando del gestor de paquetes.
• El host del registro.
• Cambios en el lockfile.
• Nombres y versiones de paquetes descargados cuando estén disponibles.
• Cualquier script de instalación que se haya ejecutado.
• Si un humano aprobó la instalación.

Esto no hace que los paquetes arbitrarios sean seguros. Hace que el cambio sea revisable.

Límites de secretos

Los secretos deben tener un alcance limitado a la tarea, ser de corta duración y estar ausentes por defecto. El sandbox más seguro no es aquel que promete que un modelo nunca revelará un secreto; es aquel donde el secreto no está presente a menos que la tarea realmente lo requiera.

Utiliza estos valores predeterminados:

• Sin credenciales de base de datos de producción en los espacios de trabajo del agente.
• Sin tokens de administrador de la nube.
• Sin claves SSH personales ni credenciales de la máquina del desarrollador.
• Credenciales de solo lectura cuando sea posible.
• Tokens separados para lecturas de paquetes, fixtures de prueba o API solo de staging.
• Redacción en registros antes de compartir artefactos.

Si el agente debe llamar a un servicio externo, proporciona un token estrecho y registra qué herramienta o comando lo usó. Evita colocar credenciales amplias en archivos que el agente pueda editar. Las variables de entorno son convenientes, pero aún pueden ser impresas por comandos, incluidas en registros o copiadas en archivos generados. Trátalas como expuestas al proceso del agente.

Registros, artefactos y pistas de auditoría

La revisión humana solo es útil cuando los revisores pueden ver lo que sucedió. Una ejecución de agente de codificación en sandbox debe preservar más que el parche final.

Captura al menos:

• El prompt de la tarea o resumen de instrucciones.
• El commit base y la rama.
• Archivos leídos y escritos cuando tu herramienta pueda registrarlos.
• Comandos ejecutados, con marcas de tiempo, directorio de trabajo, estado de salida, stdout y stderr.
• Resúmenes de instalación de paquetes y acceso a red.
• Resultados de pruebas y compilaciones.
• Archivos generados, capturas de pantalla, informes o enlaces de vista previa.
• El diff final.

Almacena los registros en una superficie de revisión que sobreviva al sandbox. Si el sandbox se destruye inmediatamente después de la ejecución, la evidencia aún debe estar disponible en la solicitud de extracción, el almacén de artefactos de CI o el registro de la plataforma de agentes.

Para equipos que usan agentes administrados, esta pista de auditoría también ayuda a comparar el rendimiento del agente. Puedes ver si los fallos provinieron de dependencias faltantes, un comando denegado, un prompt poco claro, pruebas inestables o un problema real de código.

Limpieza y reinicio

La limpieza del sandbox es un control de seguridad y costos, no solo una tarea doméstica. Al final de una ejecución:

• Detén los procesos en segundo plano.
• Cierra los puertos expuestos.
• Revoca los tokens de alcance de tarea.
• Exporta los artefactos requeridos.
• Elimina los archivos temporales que no formen parte de la revisión.
• Destruye, pausa o captura una instantánea del sandbox según el tipo de ejecución.

El reinicio efímero es el valor predeterminado más limpio para trabajo no confiable o exploratorio. Para agentes de larga duración, captura instantáneas solo después de un paso de configuración conocido como bueno, no después de actividad arbitraria del agente. Si una ejecución fallida necesita investigación, preserva el sandbox o la instantánea con una fecha de vencimiento clara.

Dónde encaja Novita Agent Sandbox

Novita Agent Sandbox está diseñado para flujos de trabajo de ejecución de agentes de IA donde el código se ejecuta dentro de espacios de trabajo en la nube aislados en lugar de en un portátil de desarrollador o un host compartido. La documentación de Novita Sandbox describe primitivas centrales que se corresponden con el patrón de esta guía: gestión del ciclo de vida del sandbox, operaciones del sistema de archivos, ejecución de comandos, plantillas y gestión del tiempo de ejecución para cargas de trabajo de agentes.

Eso hace que Novita sea adecuado para equipos que construyen flujos de trabajo de agentes de codificación, análisis de datos, agentes de navegador, evaluación o agentes de larga duración que necesitan un entorno de ejecución junto con APIs de modelo. Mantén claro el límite, sin embargo: este artículo es un patrón de implementación general para agentes de codificación al estilo Claude Code y administrados. No afirma una integración oficial con Claude Code, una asociación ni compatibilidad universal con cada producto de agente administrado.

Si estás diseñando un flujo de trabajo basado en Novita, usa los documentos del producto para la superficie de API exacta publicada y mantén tu capa de política explícita. El sandbox puede proporcionar el espacio de trabajo de ejecución aislado; tu aplicación aún debe decidir las aprobaciones de comandos, la política de red, el alcance de los secretos, la retención de artefactos y las puertas de revisión humana.

Lista de verificación de revisión de seguridad

Usa esta lista de verificación antes de permitir que un agente de codificación se ejecute más allá de un repositorio de juguete:

Pregunta	Qué buscar
¿Cuál es el límite de aislamiento?	Espacio de trabajo dedicado, límites de proceso, separación del sistema de archivos y documentación clara del proveedor
¿Qué puede leer el agente?	Acceso solo al repositorio por defecto, sin directorio de inicio del host, sin repositorios no relacionados
¿Qué puede escribir el agente?	Las rutas de origen modificables son explícitas; las rutas de configuración sensibles obtienen revisión adicional
¿Qué comandos se ejecutan automáticamente?	Se permiten comandos de prueba y formato; los comandos que cambian el estado requieren aprobación
¿Qué acceso a red existe?	Denegación predeterminada o salida con alcance; los registros de paquetes y dominios de documentación son intencionales
¿Cómo se manejan las instalaciones de paquetes?	Los cambios en lockfiles, hosts de registro y scripts de instalación se registran
¿Qué secretos están presentes?	Solo credenciales de alcance de tarea, de corta duración y de mínimo privilegio
¿Qué sucede con los registros?	Comandos, salidas, diffs y artefactos sobreviven a la limpieza del sandbox
¿Cómo se aplica la limpieza?	Los procesos en segundo plano, puertos, tokens y archivos temporales se cierran o revocan
¿Quién aprueba la fusión o el envío?	Un revisor humano verifica el código, las pruebas, los archivos sensibles a la seguridad y los artefactos generados

La regla más importante es simple: no confundas “el agente pidió permiso” con “el sistema aplicó un límite”. El modelo puede ayudar a explicar lo que quiere hacer. El tiempo de ejecución y la capa de política deben decidir lo que se le permite hacer.

Preguntas frecuentes

¿Se puede ejecutar Claude Code en un sandbox?

Sí, si tu configuración coloca al agente al estilo Claude Code dentro de un espacio de trabajo con alcance y aplica políticas de sistema de archivos, shell, red, secretos, registro y revisión a su alrededor. No asumas que un aviso de permiso local es suficiente para repositorios de producción o sensibles.

¿Es suficiente un contenedor para el aislamiento del agente de codificación?

A veces, pero la respuesta depende de tu modelo de amenaza. Los contenedores pueden ser útiles para compilaciones repetibles y separación de dependencias, pero las cargas de trabajo sensibles a la seguridad deben evaluar el límite del kernel, los montajes del host, los valores predeterminados de red, los privilegios de ejecución y la documentación del proveedor antes de tratar un contenedor como el límite completo del sandbox.

¿Se debería permitir a los agentes instalar paquetes?

Pueden hacerlo, pero las instalaciones de paquetes deben tratarse como eventos controlados de la cadena de suministro. Prefiere listas blancas de registro o espejos, revisión de lockfiles, registro de scripts de instalación y aprobación para nuevas dependencias o comandos que obtengan y ejecuten código remoto.

¿Qué debería verificar un revisor humano antes de fusionar?

Revisa el diff final, los comandos ejecutados, las pruebas realizadas, los cambios en paquetes y lockfiles, los archivos de CI/despliegue modificados, los artefactos generados y cualquier acción denegada o que requiera aprobación. Para repositorios sensibles a la seguridad, revisa la propia política del sandbox como parte del cambio.

¿Novita Agent Sandbox se integra oficialmente con Claude Code?

Este artículo no hace esa afirmación. Novita Agent Sandbox proporciona primitivas de ejecución aisladas para flujos de trabajo de agentes, mientras que Claude Code y los productos de agentes administrados tienen sus propias interfaces y modelos de permisos específicos del producto. Valida la ruta de integración exacta con los documentos actuales del producto antes de publicar comandos ejecutables.

Artículos recomendados

• Construyendo un agente de codificación con Novita Agent Sandbox
• Ejecuta evaluaciones de Harbor Agent en Novita Agent Sandbox
• Cómo usar Codex con modelos de Novita AI