Configurar políticas de sandbox

Que la ejecución de un agente esté dentro de un sandbox se decide en el servidor, al arrancar (--sandbox). El interruptor Activar sandboxing y el selector Backend, ambos en Ajustes → Servidor → Diagnóstico y privacidad, son preferencias almacenadas en tu dispositivo. La detección de host de la tarjeta Aislamiento reporta qué puede envolver el host del servidor.

Dos controles llegan hasta una ejecución y esta guía cubre ambos: las reglas de acciones de Ajustes → Espacio de trabajo → Permisos de agentes, que deciden qué puede enviar, abrir o alcanzar un agente, y la propia bandera --sandbox del servidor.

Qué limita la ejecución de un agente

Seis cosas sujetan a un agente. La primera es el sandbox del sistema operativo y es la única condicional: las otras cinco rigen en cualquier host.

Frontera	Qué hace
El sandbox del sistema operativo	Seatbelt en macOS, bubblewrap en Linux y WSL2. Envuelve la CLI de Claude Code, los adaptadores ACP y la herramienta bash del arnés. No existe en Windows ni en Linux sin bwrap y socat
Su propio worktree	Cada conversación recibe un checkout con copia en escritura. El checkout original se incorpora a la ejecución como ruta con escritura denegada y el sandbox es lo que lo hace cumplir
Credenciales gestionadas por el broker	El broker de credenciales emite un entorno por ejecución y lo revoca al desmontarla. Su token de GitHub puede leer pero no hacer push: un push pasa por Control Center, que primero pregunta a la regla de push
Barandillas de acciones	Toda herramienta que muta declara sus clases de efecto y la barandilla las resuelve antes de que se ejecute la llamada. Una decisión prompt sin ningún aprobador conectado se deniega
Sanitización del entorno	ACP y la herramienta bash del arnés reciben un entorno filtrado. Claude Code, a través de NoSandboxAdapter, hereda el entorno del host
La superficie de herramientas del modo	Un modo de solo lectura elimina por completo las herramientas que mutan el worktree y fija el verbo de salida propio del modo para que aún pueda entregar

Tres cosas siguen siendo más débiles de lo que parecen:

• Solo el arnés integrado aplica la compuerta de herramientas, los contratos de finalización y las reglas estructurales del modo. El adaptador de Claude Code no lo hace. Claude Code, en particular, se lanza con --dangerously-skip-permissions, porque un claude -p no interactivo se bloquearía para siempre en su propia solicitud de aprobación; así que las llamadas de lectura, escritura y edición del propio Claude ni las ve Control Center ni pasan por sus compuertas, y sus comandos de bash solo los revisa un hook que lee la línea de comandos. Donde el sandbox está activo, es la frontera que las rodea.
• Las herramientas de archivos en proceso del arnés (read, write, edit, apply patch, search, find, search_files) se ejecutan dentro del proceso del servidor, así que ningún perfil de sandbox las limita. Solo la herramienta bash pasa por el ejecutor de comandos con sandbox. Esas herramientas están acotadas por su propio confinamiento de rutas más las barandillas de acciones.
• En un host sin backend, la primera fila no se aplica en absoluto. ACP y la herramienta bash del arnés recurren a la sanitización del entorno más la política de comandos; Claude Code hereda el entorno del host a través de NoSandboxAdapter. El servidor lo indica en su registro de arranque. Comprueba el tuyo más abajo.

Decidir qué puede enviar un agente

No hay ningún interruptor por agente para git push, GitHub, tickets o la red. Cada uno es una regla de acción:

Regla	Valor predeterminado	Qué cubre
Enviar a un remoto	Preguntar primero	Cada git push a GitHub, sea cual sea el adaptador
Abrir una pull request	Preguntar primero	gh pr create y las herramientas de pull requests
Publicar una revisión o fusionar	Preguntar primero	gh pr merge, gh pr review, gh pr comment, gh pr close
Escribir en un rastreador externo	Preguntar primero	Escrituras de tickets con las herramientas de Control Center y gh issue
Acceder a la red	Permitir	Si el sandbox tiene red, y las herramientas web del arnés

1. Ve a Ajustes → Espacio de trabajo → Permisos de agentes
2. Elige el ámbito —Espacio de trabajo, Agente o Espacio— y, en la fila de la regla, elige Permitir, Preguntar primero o Denegar

Las reglas de push limitadas a ramas, como una que deniega los push a main, también se aplican: consulta Barandillas.

Punto de control: pide al agente que haga push de una rama. Con Preguntar primero recibes una aprobación que indica el repositorio y las refs; con Denegar, git muestra ! [remote rejected] <ref> (Control Center policy: …).

Cómo llega cada regla a la ejecución:

• El push se aplica por lo que tiene la ejecución. Su token de GitHub es un token de instalación de GitHub App de solo lectura, que puede leer contenido y trabajar con pull requests. Su configuración de git envía cada push a GitHub a una pasarela de loopback en cc_server, que pregunta a la regla y solo entonces reenvía el push con un token de escritura que el agente nunca ve. La pasarela solo reenvía al repositorio propio del worktree o a un repositorio de GitHub vinculado al espacio de trabajo. Esto vale para todos los adaptadores.
• Las pull requests y las issues desde un shell se reconocen por la línea de comandos, en la herramienta bash del arnés y, mediante un hook, en la herramienta Bash de Claude Code. Un agente que oculte el comando (un script, eval, una llamada directa a la API) se salta esta comprobación, pero no la pasarela de push.
• Las claves de tickets nunca se colocan en el sandbox. Los agentes escriben tickets con las herramientas MCP de Control Center, que preguntan a la regla.
• La red se resuelve una sola vez, cuando arranca la ejecución. Denegar desactiva la red del sandbox; Permitir y Preguntar primero la dejan activada, y con Preguntar primero las herramientas web_fetch y web_search del arnés siguen preguntando en cada llamada. Mientras la red está activada, GitHub siempre está en la lista de permitidos de salida.

Sin GitHub App, la regla de push es solo orientativa

Si no hay ninguna GitHub App configurada, la ejecución recibe el token de acceso personal alternativo, que no se puede restringir a solo lectura. git push sigue pasando por la pasarela y la regla, pero el código que use directamente el token puede hacer push saltándosela. Configura la GitHub App para que la regla sea vinculante.

La credencial de GitHub de la ejecución es siempre la del broker —un token de instalación de la GitHub App con alcance de repositorio, o el PAT alternativo—, nunca el token propio almacenado de la persona solicitante. El PAT del servidor se retiene a una ejecución que actúa por una persona que no es la propietaria y no ha conectado GitHub.

Comprobar si tus ejecuciones de agentes están dentro de un sandbox

Dos cosas lo deciden, ambas en el servidor: si el host ofrece un backend y si --sandbox está activado. Compruébalas en ese orden.

1. Ve a Ajustes → Servidor → Diagnóstico y privacidad
2. Lee la tarjeta Aislamiento. El dato Host es la máquina en la que se ejecuta cc_server, no la máquina que estás viendo. El campo Backend indica Native sandbox (Seatbelt en macOS, bubblewrap en Linux y WSL2) o No isolation. El dato En vigor es la preferencia de este dispositivo, no el envoltorio que el servidor usa realmente.
3. Lee el registro de arranque del servidor. Imprime exactamente una de estas tres líneas:
   • agent sandbox ON más la nota del backend: las ejecuciones van envueltas
   • no OS-native agent sandbox on this host más una sugerencia de instalación donde la haya: las ejecuciones no van envueltas
   • agent sandbox DISABLED by --sandbox off: una desactivación deliberada

GET /healthz no reporta el estado del sandbox, así que el registro de arranque es la comprobación.

Para desactivar el sandbox a propósito —un host donde el perfil se comporta mal es la razón de que exista esta opción—, inicia el servidor con --sandbox off o define CC_SERVER_SANDBOX=off. El valor predeterminado es on, y on significa “usar un backend si el host tiene uno”, nunca “exigir uno”.

Dos situaciones nunca reciben un envoltorio de sandbox nativo. En Windows, la sonda nativa siempre reporta no disponible y no hay nada que instalar: el despacho de agentes usa none. El backend microvm es aparte (terminales interactivos y rigs) y está condicionado a la sonda de su propio runtime. En Linux y WSL2, tanto bwrap como socat deben estar en el PATH; sin ellos, la sonda reporta no disponible y nombra los paquetes que faltan.

En Linux/WSL2 con bubblewrap instalado, los globs de archivos secretos de la política estándar no se pueden aplicar a archivos que un agente cree después. Esa ejecución nativa ahora falla en lugar de ignorar las reglas en silencio. Por lo tanto, una sonda de arranque positiva no garantiza que un despacho en Linux pueda iniciarse. --sandbox off es una desactivación deliberada y sin confinamiento, no una frontera de seguridad sustituta.

Saber qué prohíbe ya un modo

El modo se almacena por espacio y alimenta al resolutor de barandillas como la capa de preajuste del modo. Tres de los cuatro modos son de solo lectura, y un modo de solo lectura rechaza once clases de efecto de plano:

Modo	Worktree	Rechazado por el preajuste
Agente (chat)	Se puede escribir	Nada: se aplican los valores predeterminados integrados
Plan	Solo lectura	Eliminar un archivo, escribir fuera del worktree, hacer commit, hacer push, abrir una PR, publicar o fusionar, escribir en un rastreador externo, instalar un paquete, ejecutar un proceso, cambiar la estructura del espacio de trabajo, arrancar o controlar un recinto
Revisión	Solo lectura	Las mismas once. No lo puede seleccionar el usuario: el compositor solo ofrece Agente, Plan y Orquestación
Orquestación	Solo lectura	Las mismas once

El acceso a la red y a los secretos deliberadamente no los rechaza un modo de solo lectura: la investigación es justo el objetivo de uno.

Exigir aprobación antes de que se ejecute una acción

La aprobación es una decisión de las barandillas, no un ajuste del sandbox.

1. Ve a Ajustes → Espacio de trabajo → Permisos de agentes
2. Define la clase de acción como Preguntar primero en el ámbito de espacio de trabajo, agente o espacio

Una decisión de Preguntar primero interrumpe la ejecución y te pregunta. Si no hay ningún aprobador conectado, falla en cerrado y la acción se deniega. Consulta Configurar barandillas para ver el orden de resolución completo.

Solución de problemas

Un agente no puede hacer push y yo nunca lo denegué

Lee lo que ha mostrado git. Control Center policy: … significa que una regla denegó el push o que un Preguntar primero quedó sin respuesta. … is not linked to this workspace significa que el push apunta a un repositorio que no es el del worktree ni está vinculado al espacio de trabajo. Control Center has no GitHub credential that can push … significa que la GitHub App no está instalada en ese repositorio y que ninguna credencial alternativa podía hacer push: instala la App en él o conecta GitHub.

La tarjeta Aislamiento no reporta ningún sandbox nativo

Entonces las ejecuciones de agentes en ese host no van envueltas por Seatbelt ni bubblewrap y las fronteras restantes son todo lo que tienes. En Linux y WSL2, instala las dos herramientas que falten —sudo apt-get install bubblewrap socat— y reinicia el servidor; el registro de arranque debería indicar entonces que el sandbox está activado. En Windows no hay ningún backend nativo que instalar, así que en su lugar refuerza las barandillas: consulta Configurar barandillas.

Un agente llegó a un archivo fuera de su worktree

La herramienta con la que llegó decide si esto es lo esperado.

Las herramientas de archivos en proceso del arnés (read, write, edit, apply patch, search, find, search_files) se ejecutan en el proceso del servidor, así que no se les aplica ningún perfil de sandbox: su límite es su propio confinamiento de rutas más las barandillas. Un comando bash o la CLI de Claude Code sí van envueltos donde existe un backend, y tus checkouts registrados tienen la escritura denegada dentro de ese envoltorio en todos los modos, incluidas sus formas resueltas por enlaces simbólicos (en macOS, una ruta a la que se llega por /tmp o /var/folders se resuelve bajo /private y ahora se deniegan ambas formas). En un host sin backend, nada de eso se aplica. De cualquier manera, las barandillas pueden rechazar Write outside the worktree de plano.

Guías relacionadas

• Configurar barandillas
• Crear y configurar un agente
• Diagnosticar un agente
• Backends de sandbox
• CLI de cc_server: la bandera --sandbox

Conceptos relacionados

• Sandbox y seguridad
• Modos