Skip to main content
La opción --sandbox ejecuta la CLI con aislamiento a nivel del sistema operativo, aplicando los ámbitos activos de permisos de lectura y escritura a nivel del sistema operativo y, opcionalmente, restringiendo el tráfico de red.

​
Cómo funciona el sandbox

Cuando el sandbox está activo:
  • Las rutas con permiso de escritura se derivan de los ámbitos de permiso Write(...) concedidos más el directorio del workspace
  • Las rutas legibles se derivan de los ámbitos Read(...) concedidos (los valores predeterminados de la plataforma, como /usr/bin, siempre son legibles)
  • Los ámbitos concedidos a mitad de la sesión amplían dinámicamente el sandbox para los comandos posteriores
Si falla la resolución del sandbox (p. ej., porque las herramientas de sandboxing no están disponibles en la plataforma del usuario), la CLI se negará a iniciarse en lugar de ejecutarse sin sandbox. Este comportamiento de fallo seguro se aplica tanto si el sandbox se habilitó mediante una configuración del equipo como si el usuario pasó --sandbox directamente, lo que garantiza que la intención de seguridad nunca se omita de forma silenciosa.Causas comunes de fallo en la resolución del sandbox:
  • Windows: El sandbox a nivel del sistema operativo no es compatible actualmente con Windows. Las sesiones fallarán de inmediato cuando se pase --sandbox o cuando la aplicación del sandbox esté configurada como Obligatoria, incluso cuando la CLI se ejecute como servidor ACP dentro de un IDE (p. ej., Devin Desktop).
  • Linux: El sandboxing requiere que bubblewrap (bwrap) y socat estén instalados. Si faltan, las sesiones fallarán de inmediato y mostrarán instrucciones de instalación.
  • Errores de ámbito de permisos: Rutas no válidas en ámbitos de permisos que no se pueden resolver.

​
Filtrado de red

El filtrado de red del sandbox es actualmente inestable. Si necesitas esta función, ponte en contacto con el representante de tu cuenta para conocer los plazos previstos de estabilidad.
Configura el filtrado de red a nivel de dominio para el sandbox en la sección sandbox de tu archivo de configuración (solo en la configuración de usuario). Cuando --sandbox está activo y el filtrado de dominios está configurado, se inicia un proxy de red gestionado en la interfaz de loopback y el sandbox restringe todo el tráfico de los procesos hijo para que pase por él. Sintaxis de los patrones de dominio: Ejemplo:
El filtrado de dominios se aplica cuando el sandbox está activo (--sandbox). Sin --sandbox, la sección de sandbox se ignora.

​
Comandos excluidos

A veces, un comando específico necesita ejecutarse fuera del sandbox; por ejemplo, comandos de git que deben acceder a credenciales o hooks que el sandbox bloquea. La sección de configuración sandbox.excluded te permite excluir del aislamiento del sandbox los comandos que coincidan, usando la misma sintaxis de reglas Exec(...) que permisos: Ejemplo:
Resolución de reglas: para cada comando, dentro de un mismo origen se aplica la regla coincidente más específica (p. ej., Exec(git push *) prevalece sobre Exec(git *)), y cuando coinciden tanto la configuración del usuario como Team Settings, prevalece el veredicto más restrictivo (deny > ask > allow). Los comandos que no coinciden con ninguna regla —incluidos los casos en que sandbox.excluded no está configurado en absoluto— siempre se ejecutan dentro del sandbox.
  • Solo se admiten reglas Exec(...) en sandbox.excluded; cualquier otro tipo de regla (p. ej., Read(...), Write(...)) se ignora y genera una advertencia.
  • La exclusión es fail-closed: si un comando no puede resolverse de forma segura (p. ej., si no puede analizarse), permanece dentro del sandbox.
  • Las exclusiones se aplican a la ruta de ejecución predeterminada por comando. Los comandos ejecutados mediante un shell PTY persistente (sesiones interactivas o cuando pty_for_noninteractive_exec está habilitado) siempre permanecen dentro del sandbox.

​
Aplicación en Enterprise

Los Admin de Enterprise pueden controlar el comportamiento del sandbox en toda su organización desde Team Settings.

​
Modo de aplicación del sandbox

Establece el nivel de aplicación del flag --sandbox en toda tu organización:
  • Opcional (predeterminado) — Los usuarios eligen si pasar --sandbox. No se aplica ninguna restricción.
  • Obligatorio — El flag --sandbox se activa de forma forzada para todos los usuarios, aunque no lo pasen en la línea de comandos. Todas las sesiones de la CLI se ejecutan con un sandbox del sistema de archivos a nivel del sistema operativo que aplica ámbitos de permisos de lectura y escritura.
En el futuro, un modo Estricto podría bloquear por completo la configuración del sandbox e impedir que los usuarios modifiquen sus ajustes.
Asegúrate de que todas las máquinas de destino estén aprovisionadas antes de establecer el modo de aplicación del sandbox en Obligatorio en toda tu organización. Si hay usuarios que usan Windows, no podrán ejecutar la CLI hasta que el sandbox a nivel del sistema operativo sea compatible con Windows o la política se flexibilice a Opcional.

​
Filtrado de dominios de Enterprise

Los Admin también pueden configurar listas de permitidos y listas de denegación para toda la organización:
  • Lista de permitidos — Cuando se configura, solo se puede acceder a los dominios de esta lista a través del proxy de red del sandbox. Esta lista es determinante: reemplaza por completo cualquier allowed_domains configurado por el usuario. Los usuarios no pueden agregar dominios adicionales para eludir las restricciones del Admin.
  • Lista de dominios de denegación — Dominios que siempre se bloquean. Los dominios denegados de Enterprise son aditivos: se combinan con los denied_domains locales del usuario, lo que hace que la lista resultante sea más restrictiva.
Cómo interactúan las listas de dominios de Enterprise y del usuario:
Como los denied_domains locales del usuario se conservan y se combinan de forma aditiva, un usuario podría denegar un dominio que aparezca en la lista de permitidos de Enterprise. Esto es intencional: el efecto combinado siempre es más restrictivo, nunca menos. Si esto causa problemas de acceso, el usuario debe eliminar la entrada en conflicto de su configuración local.

​
Comandos excluidos de Enterprise

Los Admin también pueden establecer en Team Settings reglas de comandos excluidos para toda la organización:
  • Allow / ask excluidos — Reglas Exec(...) para comandos que pueden ejecutarse fuera del sandbox en toda la organización, automáticamente o tras una confirmación.
  • Deny excluido — Reglas Exec(...) para comandos que nunca deben ejecutarse fuera del sandbox. Un deny del equipo anula cualquier allow o ask a nivel de usuario para los comandos que coincidan, por lo que los usuarios no pueden excluir comandos que sus Admin hayan bloqueado.
Las reglas del equipo y del usuario se resuelven en conjunto: la regla coincidente más específica prevalece dentro de cada origen, y el resultado más restrictivo prevalece entre orígenes (deny > ask > allow). Ejemplo: bloquear todas las exclusiones excepto gh. Un deny con comodín y una excepción allow mantiene todos los comandos dentro del sandbox salvo gh, independientemente de lo que los usuarios configuren localmente. Estos valores van en la configuración de excluded-commands de Team Settings (no en el archivo de configuración del usuario, por lo que no hay una clave sandbox contenedora):
Como la regla más específica Exec(gh *) prevalece sobre el comodín Exec(**), los comandos gh se ejecutan fuera del sandbox, mientras que todo lo demás permanece dentro, y el comodín deny a nivel de equipo prevalece sobre cualquier regla allow o ask a nivel de usuario para otros comandos.

​
Más información