Modo sandbox do Gemini CLI: ativação, backends e segurança com YOLO
O guia ilustrado e direto ao ponto do sandbox no Gemini CLI: inicie com -s, torne-o permanente, escolha o backend certo para o seu sistema e dê um cinto de segurança ao modo YOLO.
Resumo
- Execute gemini -s e toda a sessão — comandos de shell, edições de arquivos, chamadas de rede — roda dentro de um sandbox isolado; um selo de sandbox aparece no rodapé para você ver que está ativo.
- São três formas de ativar, aplicadas por ordem de precedência: a flag -s / --sandbox, a variável de ambiente GEMINI_SANDBOX, ou "sandbox": true no objeto tools do settings.json.
- O backend depende do sistema: perfis Seatbelt no macOS (permissive-open por padrão), gVisor runsc no Linux para o isolamento mais forte, e contêineres Docker ou Podman no restante.
- O modo YOLO (--yolo) pula todos os pedidos de permissão — use junto com o sandbox. A v0.61.0 (23 de setembro de 2026) reforçou as fronteiras do sistema de arquivos do sandbox e isolou o estado do 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
Documentação: google-gemini/gemini-cli (GitHub)
Os quadros vêm do capítulo de sandbox do curso da freeCodeCamp; nomes de flags, configurações e perfis foram conferidos na documentação oficial do sandbox e nas notas da versão v0.61.0.
Créditos das capturas: freeCodeCamp.org e lustoykov — gravações usadas como referência visual com atribuição; todo o texto dos passos é nosso.
Sandbox no Gemini CLI, passo a passo
Rode sua primeira sessão em sandbox
- 1
Entenda o que o sandbox realmente isola
O sandbox afasta do seu sistema as operações que tornam um agente de IA perigoso — comandos de shell, escritas de arquivos e chamadas de rede. O Gemini CLI v0.61.0 (23 de setembro de 2026) reforçou as fronteiras do sistema de arquivos do sandbox e isolou o estado do runtime, fechando rotas de injeção indireta de prompt via arquivos de build e flags não confiáveis.
Onde o sandbox se encaixa: uma biblioteca de isolamento a nível de sistema, escolhida por plataforma.Ver em 140:00 - 2
Inicie direto no sandbox com a flag
O caminho mais rápido é a flag de comando: execute gemini -s (forma longa --sandbox). A primeira execução pode levar um minuto porque a imagem do sandbox talvez precise ser baixada. Para usos pontuais, combine com um prompt: gemini -s -p "analyze the code structure".
Flag ligada, selo no rodapé — a conferência de dois segundos.Ver em 140:50 - 3
Conheça as três formas de ativar — e qual vence
O Gemini CLI resolve o sandbox por ordem de precedência: primeiro a flag -s / --sandbox, depois a variável de ambiente GEMINI_SANDBOX (true, docker, podman, sandbox-exec, runsc ou lxc), por fim a entrada "sandbox" no objeto tools do seu settings.json.
A documentação oficial lista as três rotas de ativação em ordem de precedência.Ver em 145:45 - 4
Confirme no rodapé que a sessão está em sandbox
Quando a CLI sobe, a barra de status mostra um selo de sandbox com a versão do componente, ao lado do seletor de modelo. Sem selo, sem sandbox — volte e verifique qual flag ou configuração você achava que o ativava.
Uma sessão real em sandbox: o selo fica ao lado de Auto (Gemini 3).Ver em 146:40
Escolha o backend certo para o seu sistema
- 5
No macOS, use o Seatbelt embutido
O macOS não precisa de contêineres: o Gemini CLI envolve o processo com o Seatbelt (sandbox-exec). O perfil padrão, permissive-open, confina a escrita ao diretório do projeto e mantém leitura e rede abertas. Endureça com a variável de ambiente SEATBELT_PROFILE — permissive-proxied, restrictive-open, restrictive-proxied, strict-open ou strict-proxied.
- 6
No Linux ou WSL2, conheça o gVisor runsc
O gVisor do Google — o runtime runsc — oferece o isolamento mais forte disponível: os contêineres rodam sobre um kernel em espaço de usuário que intercepta cada chamada de sistema. Selecione explicitamente com GEMINI_SANDBOX=runsc ou "sandbox": "runsc" (nunca é detectado automaticamente) e o Gemini CLI executará docker run --runtime=runsc para você.
A documentação posiciona o runsc como o backend mais forte, exclusivo do Linux.Ver em 141:20 - 7
Instale o runtime runsc
No Ubuntu — nativo ou dentro do WSL2 — um comando do apt traz o runtime do gVisor: sudo apt get install runsc. Você também precisa do Docker instalado e rodando, porque o Gemini CLI opera o runsc como um runtime do Docker, não como ferramenta avulsa.
Digitando o comando de instalação num terminal WSL2 Ubuntu.Ver em 143:35 - 8
Confira se a instalação ficou no lugar
O apt desempacota o runsc direto do repositório de atualizações de segurança do Ubuntu — sem PPA extra. Sem este passo, um futuro gemini -s no Linux falha ou cai silenciosamente no backend de contêineres: confirme o pacote antes da primeira execução em sandbox.
O apt conclui o desempacotamento do runsc no Ubuntu 24.04.Ver em 144:15 - 9
Prefere contêineres? Docker ou Podman em qualquer sistema
O sandbox por contêiner funciona onde o Docker ou o Podman rodar, e ambos precisam estar instalados e em execução antes de começar — rode docker uma vez para confirmar que a CLI responde. O sandbox usa a imagem ghcr.io/google/gemini-cli:latest por padrão e monta seu diretório de trabalho exatamente no mesmo caminho absoluto dentro do contêiner.
Rodar docker uma vez para confirmar que a engine responde.Ver em 145:30
Rode o modo YOLO sem suor
- 10
Combine o sandbox com o modo YOLO
gemini --yolo (abreviação de --approval-mode=yolo) pula perigosamente todos os pedidos de permissão — exatamente o que execuções autônomas precisam e exatamente para o que um sandbox existe. Inicie as sessões YOLO com a flag de sandbox para que as permissões puladas continuem dentro do ambiente isolado.
O modo YOLO em um slide: sem interrupções, todas as permissões liberadas.Ver em 148:20 - 11
Verifique que as execuções autônomas seguiram em sandbox
Durante as sessões YOLO o rodapé acende um selo azul de YOLO Mode — o sinal de que as permissões estão sendo puladas. Depois da execução, o resumo de interação do /stats mostra quais ferramentas dispararam, e o selo de sandbox continua sendo a prova de que o trabalho aconteceu dentro da caixa.
O selo YOLO Mode no rodapé de uma sessão autônoma concluída.Ver em 147:40
Imagens de sandbox próprias e flags de contêiner
A imagem de contêiner padrão serve para trabalho de código genérico. Quando seu projeto precisa da própria toolchain — ou o ambiente de contêineres te atrapalha — o Gemini CLI dá quatro botões de ajuste.
- 1Aponte para qualquer imagem: defina GEMINI_SANDBOX_IMAGE, ou a forma de objeto no settings.json — "sandbox": "command": "docker", "image": "..." (a JSON object). Qualquer imagem Docker ou Podman com bash funciona.
- 2Construa a sua: coloque um .gemini/sandbox.Dockerfile na raiz do projeto e rode com BUILD_SANDBOX=1 — o Gemini CLI constrói a imagem automaticamente. A construção automática só funciona executando a CLI do código-fonte; em instalações via npm, referencie uma imagem pré-construída.
- 3Ajuste o comando do contêiner: a SANDBOX_FLAGS injeta flags extras de docker/podman — por exemplo, export SANDBOX_FLAGS="--security-opt label=disable" resolve recusas de montagem por SELinux no Podman.
- 4Corrija a propriedade de arquivos no Linux: o sandbox mapeia permissões de usuário automaticamente, mas SANDBOX_SET_UID_GID=true força o UID/GID do host quando os arquivos gerados saem com dono errado.
Roda a própria Gemini CLI dentro de um contêiner e quer sandbox ali dentro? Monte o /var/run/docker.sock para que a CLI possa criar contêineres irmãos via daemon do host, e faça o caminho do workspace coincidir exatamente com o caminho absoluto do host — quem resolve as montagens é o daemon do host, não o contêiner.
Solução de problemas: erros, acesso a arquivos, desativação
Quase todo problema de sandbox se resume a cinco padrões. Antes de tudo, reproduza com saída de debug: DEBUG=1 gemini -s -p "your prompt".
- 1"Operation not permitted" — o comando precisa de acesso fora do sandbox. Mude para um perfil mais permissivo (macOS: SEATBELT_PROFILE) ou adicione as montagens necessárias.
- 2Comandos que faltam dentro do sandbox — embuta suas ferramentas em uma imagem própria ou instale via sandbox.bashrc. Lembre: a automação BUILD_SANDBOX é só para código-fonte.
- 3Falhas de rede — confira se o perfil ativo permite rede e revise a configuração de proxy; os perfis -proxied encaminham o tráfego pelo proxy do sandbox.
- 4Arquivos criados com dono errado no Linux — alterne a SANDBOX_SET_UID_GID (true força o UID/GID do host, false desativa o mapeamento).
- 5Windows deixou arquivos marcados com integridade baixa — o sandbox nativo usa icacls para marcar caminhos graváveis; restaure com icacls "C:\path\to\dir" /setintegritylevel Medium.
Para ver o que o sandbox alcança, pergunte à própria CLI: gemini -s -p "run shell command: env | grep SANDBOX" lista as variáveis de ambiente do sandbox e mount | grep workspace mostra as montagens. Não há etapa de exportação de arquivos — sandboxes de contêiner montam seu projeto no mesmo caminho absoluto, então as edições caem direto na sua pasta. Para desativar: tire a flag -s, remova a GEMINI_SANDBOX ou apague a entrada "sandbox" do settings.json; o sandbox no nível de ferramentas tem chave própria, "security": "toolSandboxing": false (exige reiniciar).