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.
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.
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.
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.
| Opción | Tipo | Predeterminado | Descripción |
|---|
allowed_domains | string[] | [] | Patrones de dominio permitidos a través del proxy. Cuando no está vacío, solo se permiten los dominios que coinciden (modo de lista de permitidos) |
denied_domains | string[] | [] | Patrones de dominio siempre bloqueados. Las reglas de denegación tienen prioridad sobre las reglas de permiso |
network_mode | string | "full" | "full" permite todos los métodos HTTP; "limited" permite solo GET/HEAD/OPTIONS |
| Patrón | Coincide con |
|---|
example.com | Solo coincidencia exacta |
*.example.com | Cualquier subdominio (no el dominio raíz) |
**.example.com | El dominio raíz y cualquier subdominio |
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
El filtrado de dominios se aplica cuando el sandbox está activo (--sandbox). Sin --sandbox, la sección de sandbox se ignora.
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:
| Opción | Tipo | Descripción |
|---|
excluded.allow | string[] | Los comandos que coincidan se ejecutan fuera del sandbox automáticamente |
excluded.ask | string[] | Los comandos que coincidan se ejecutan fuera del sandbox después de que el usuario apruebe una confirmación |
excluded.deny | string[] | Los comandos que coincidan nunca se excluyen; siempre permanecen dentro del sandbox |
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
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.
Modo de aplicación del sandbox
--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
- 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:
| Escenario | Configuración de Enterprise | Configuración del usuario | Resultado efectivo |
|---|
| El Admin configura una lista de permitidos | allowed_domains: ["github.com"] | allowed_domains: ["npmjs.org"] | Solo se permite github.com (Enterprise reemplaza la lista del usuario) |
| El Admin configura una lista de denegación | denied_domains: ["evil.com"] | denied_domains: ["risky.io"] | Tanto evil.com como risky.io se bloquean (combinados) |
| No hay lista de permitidos del Admin | allowed_domains: [] | allowed_domains: ["github.com"] | Se usa la lista de permitidos 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
- 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):
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
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.
