Modo sandbox de Gemini CLI: activación, backends y seguridad con YOLO
La guía ilustrada y sin relleno del sandbox de Gemini CLI: arranca con -s, hazlo permanente, elige el backend adecuado para tu sistema operativo y dale un cinturón de seguridad al modo YOLO.
Lo esencial
- Ejecuta gemini -s y toda la sesión — comandos de shell, ediciones de archivos, llamadas de red — corre dentro de un sandbox aislado; aparece una insignia de sandbox en la barra inferior para que veas que está activo.
- Hay tres formas de activarlo, aplicadas por orden de precedencia: la bandera -s / --sandbox, la variable de entorno GEMINI_SANDBOX, o "sandbox": true en el objeto tools de settings.json.
- El backend depende del sistema: perfiles Seatbelt en macOS (permissive-open por defecto), gVisor runsc en Linux para el aislamiento más fuerte, y contenedores Docker o Podman en el resto.
- El modo YOLO (--yolo) se salta todas las peticiones de permiso — úsalo junto al sandbox. La v0.61.0 (23 de septiembre de 2026) reforzó los límites del sistema de archivos del sandbox y aisló el estado del runtime.
Gemini CLI Essentials – Full Course (sandboxing chapter)
Canal: freeCodeCamp.org3:49:40
Gemini CLI: Everything You Need To Know (Full Tutorial)
Canal: lustoykov42:54
Sandboxing in Gemini CLI — official documentation
Documentación: google-gemini/gemini-cli (GitHub)
Los fotogramas provienen del capítulo de sandbox del curso de freeCodeCamp; los nombres de banderas, ajustes y perfiles se verificaron contra la documentación oficial del sandbox y las notas de la versión v0.61.0.
Créditos de capturas: freeCodeCamp.org y lustoykov — grabaciones usadas como referencia visual con atribución; todo el texto de los pasos es nuestro.
Sandbox para Gemini CLI, paso a paso
Lanza tu primera sesión en sandbox
- 1
Sabe qué aísla realmente el sandbox
El sandbox aparta de tu sistema las operaciones que vuelven peligroso a un agente de IA: comandos de shell, escrituras de archivos y llamadas de red. Gemini CLI v0.61.0 (23 de septiembre de 2026) reforzó los límites del sistema de archivos del sandbox y aisló el estado del runtime, cerrando las vías de inyección indirecta de prompts mediante archivos de build y banderas no fiables.
Dónde encaja el sandbox: una librería de aislamiento a nivel de sistema, según la plataforma.Ver en 140:00 - 2
Arranca directo en sandbox con la bandera
La vía rápida es la bandera de línea de comandos: ejecuta gemini -s (forma larga --sandbox). El primer arranque puede tardar un minuto porque la imagen del sandbox quizá deba descargarse. Para usos puntuales, combínala con un prompt: gemini -s -p "analyze the code structure".
Bandera activada, insignia en la barra inferior — la comprobación de dos segundos.Ver en 140:50 - 3
Aprende las tres formas de activarlo — y cuál manda
Gemini CLI resuelve el sandbox por orden de precedencia: primero la bandera -s / --sandbox, luego la variable de entorno GEMINI_SANDBOX (true, docker, podman, sandbox-exec, runsc o lxc), y por último la entrada "sandbox" en el objeto tools de tu settings.json.
La documentación oficial enumera las tres rutas de activación por precedencia.Ver en 145:45 - 4
Confirma en la barra inferior que la sesión está en sandbox
Cuando la CLI arranca, la barra de estado muestra una insignia de sandbox con la versión del componente, junto al selector de modelo. Sin insignia no hay sandbox: vuelve y revisa qué bandera o ajuste creías que lo activaba.
Una sesión real en sandbox: la insignia queda junto a Auto (Gemini 3).Ver en 146:40
Elige el backend adecuado para tu sistema
- 5
En macOS, apóyate en Seatbelt
macOS no necesita contenedores: Gemini CLI envuelve el proceso con Seatbelt (sandbox-exec). El perfil por defecto, permissive-open, confina la escritura al directorio del proyecto y deja abiertas la lectura y la red. Endúrzalo con la variable de entorno SEATBELT_PROFILE: permissive-proxied, restrictive-open, restrictive-proxied, strict-open o strict-proxied.
- 6
En Linux o WSL2, conoce gVisor runsc
gVisor de Google — el runtime runsc — ofrece el aislamiento más fuerte disponible: los contenedores corren sobre un kernel de espacio de usuario que intercepta cada llamada al sistema. Selecciónalo explícitamente con GEMINI_SANDBOX=runsc o "sandbox": "runsc" (nunca se autodetecta) y Gemini CLI ejecutará docker run --runtime=runsc por ti.
La documentación presenta runsc como el backend más fuerte, exclusivo de Linux.Ver en 141:20 - 7
Instala el runtime runsc
En Ubuntu —nativo o dentro de WSL2— un comando de apt trae el runtime de gVisor: sudo apt get install runsc. También necesitas Docker instalado y en ejecución, porque Gemini CLI maneja runsc como un runtime de Docker, no como una herramienta independiente.
Escribiendo el comando de instalación en una terminal WSL2 Ubuntu.Ver en 143:35 - 8
Comprueba que la instalación quedó lista
apt desempaqueta runsc directamente del repositorio de actualizaciones de seguridad de Ubuntu — sin PPA extra. Si te saltas este paso, un posterior gemini -s en Linux falla o cae en silencio al backend de contenedores: verifica el paquete antes de tu primera ejecución en sandbox.
apt termina de desempaquetar runsc en Ubuntu 24.04.Ver en 144:15 - 9
¿Prefieres contenedores? Docker o Podman en cualquier sistema
El sandbox por contenedores funciona donde funcione Docker o Podman, y ambos deben estar instalados y en marcha antes de empezar — ejecuta docker una vez para confirmar que la CLI responde. El sandbox usa la imagen ghcr.io/google/gemini-cli:latest por defecto y monta tu directorio de trabajo en la misma ruta absoluta dentro del contenedor.
Ejecutar docker una vez para confirmar que el motor responde.Ver en 145:30
Ejecuta el modo YOLO sin sudar
- 10
Combina el sandbox con el modo YOLO
gemini --yolo (abreviatura de --approval-mode=yolo) salta peligrosamente todas las peticiones de permiso: justo lo que necesitan las ejecuciones autónomas y justo para lo que existe un sandbox. Lanza las sesiones YOLO con la bandera de sandbox para que los permisos omitidos queden dentro del entorno aislado.
El modo YOLO en una diapositiva: sin interrupciones, todos los permisos pasan.Ver en 148:20 - 11
Verifica que las ejecuciones autónomas siguieron en sandbox
Durante las sesiones YOLO la barra inferior enciende una insignia azul de YOLO Mode: la señal de que los permisos se están omitiendo. Tras la ejecución, el resumen de interacción de /stats muestra qué herramientas se usaron, y la insignia de sandbox sigue siendo la prueba de que el trabajo ocurrió dentro de la caja.
La insignia YOLO Mode en la barra inferior de una sesión autónoma terminada.Ver en 147:40
Imágenes de sandbox propias y banderas de contenedores
La imagen de contenedor por defecto basta para trabajo de código genérico. Cuando tu proyecto necesita su propia cadena de herramientas —o tu entorno de contenedores se pone difícil— Gemini CLI te da cuatro palancas.
- 1Apunta a cualquier imagen: define GEMINI_SANDBOX_IMAGE, o la forma de objeto en settings.json — "sandbox": "command": "docker", "image": "..." (a JSON object). Sirve cualquier imagen Docker o Podman que incluya bash.
- 2Construye la tuya: coloca un .gemini/sandbox.Dockerfile en la raíz del proyecto y ejecuta con BUILD_SANDBOX=1 — Gemini CLI construye la imagen automáticamente. La construcción automática solo funciona ejecutando la CLI desde el código fuente; en instalaciones npm, referencia una imagen preconstruida.
- 3Ajusta el comando del contenedor: SANDBOX_FLAGS inyecta banderas extra de docker/podman — por ejemplo, export SANDBOX_FLAGS="--security-opt label=disable" soluciona los rechazos de montaje por SELinux en Podman.
- 4Corrige la propiedad de los archivos en Linux: el sandbox mapea permisos de usuario automáticamente, pero SANDBOX_SET_UID_GID=true fuerza el UID/GID del host cuando los archivos generados salen con dueño equivocado.
¿Ejecutas la propia Gemini CLI dentro de un contenedor y quieres sandbox dentro? Monta /var/run/docker.sock para que la CLI pueda crear contenedores hermanos vía el demonio del host, y haz que la ruta del workspace coincida exactamente con la ruta absoluta del host — quien resuelve los montajes es el demonio del host, no el contenedor.
Solución de problemas: errores, acceso a archivos, desactivación
Casi todos los problemas del sandbox se reducen a cinco patrones. Antes que nada, reproduce con salida de depuración: DEBUG=1 gemini -s -p "your prompt".
- 1"Operation not permitted" — el comando necesita acceso fuera del sandbox. Pasa a un perfil más permisivo (macOS: SEATBELT_PROFILE) o añade los puntos de montaje necesarios.
- 2Comandos que faltan dentro del sandbox — hornea tus herramientas en una imagen propia o instálalas vía sandbox.bashrc. Recuerda: la automatización BUILD_SANDBOX es solo para código fuente.
- 3Fallos de red — comprueba que el perfil activo permite red y revisa la configuración del proxy; los perfiles -proxied dirigen el tráfico por el proxy del sandbox.
- 4Archivos creados con dueño equivocado en Linux — alterna SANDBOX_SET_UID_GID (true fuerza el UID/GID del host, false desactiva el mapeo).
- 5Windows dejó archivos marcados con integridad baja — el sandbox nativo usa icacls para marcar rutas escribibles; restáuralos con icacls "C:\path\to\dir" /setintegritylevel Medium.
Para ver qué alcanza el sandbox, pregúntale a la propia CLI: gemini -s -p "run shell command: env | grep SANDBOX" lista las variables de entorno del sandbox y mount | grep workspace muestra los montajes. No hace falta exportar archivos: los sandbox de contenedores montan tu proyecto en la misma ruta absoluta, así que las ediciones caen directo en tu carpeta. Para desactivar: quita la bandera -s, elimina GEMINI_SANDBOX o borra la entrada "sandbox" de settings.json; el sandbox a nivel de herramientas tiene su propio interruptor, "security": "toolSandboxing": false (requiere reiniciar).