Modo sandbox do Copilot: o guia ilustrado
O sandbox local mantém os comandos de shell, as ferramentas de arquivos e os acessos de rede do GitHub Copilot dentro de uma caixa no nível do sistema operacional. Este passo a passo segue a demo oficial do GitHub: ativar com /sandbox, moldar a política, desligar e entregar sessões inteiras à nuvem.
Resumo rápido
- O modo sandbox executa os comandos de shell, ferramentas de arquivos e servidores MCP e LSP do Copilot dentro de um sandbox do sistema operacional — restringindo arquivos, rede e credenciais sem VM ou contêiner (Seatbelt no macOS, bubblewrap no Linux, ProcessContainer no Windows).
- No app do Copilot, o sandbox vem desligado por padrão: abra as configurações, escolha o projeto e ative "Sandbox new sessions". Na CLI, execute /sandbox enable (experimental).
- Execute /sandbox para moldar a política — abas General, Filesystem e Network na CLI; caminhos adicionais de leitura/escrita, somente leitura e negados, além de interruptores de rede e credenciais no app. As mudanças valem para novas sessões, ou via /restart-session.
- copilot --cloud move a sessão inteira para um sandbox na nuvem hospedado pelo GitHub; você volta pelo link github.com/copilot/tasks ou pela aba Agents do repositório. As configurações locais não se aplicam a sessões na nuvem.
How to run GitHub Copilot in local and cloud sandboxes | demo
Canal:GitHub (official channel)1:31
GitHub Copilot Sandboxes are SO COOL
Canal:Gwyneth Peña-Siguenza1:50
Local sandboxing in the GitHub Copilot app (public preview)
Documentação:github.blog/changelog
Configuring local sandboxing in the GitHub Copilot app
Documentação:docs.github.com
About cloud and local sandboxes for GitHub Copilot
Documentação:docs.github.com
Os quadros deste guia vêm da demo oficial de sandbox do GitHub — uma gravação limpa de terminal. O texto foi escrito a partir do vídeo e da documentação do GitHub; os nomes das configurações são citados literalmente.
As capturas de tela permanecem propriedade de seus criadores e são usadas com atribuição como referência visual. O sandbox local está em prévia pública — nomes e comportamentos podem mudar.
O passo a passo: 12 etapas
1 · Ativar o sandbox local
- 1
Inicie o Copilot no seu repositório
Abra a CLI do Copilot no seu projeto. O sandbox é um recurso experimental da CLI — o banner mostra o selo /experimental e a barra de status traz o indicador de sandbox que você vai aprender a ler.
A CLI do Copilot iniciando com o selo /experimental e o indicador de sandbox na barra de status.Assistir em 0:08 - 2
Execute /sandbox enable
Digite /sandbox e a paleta de comandos oferece exatamente duas chaves: enable e disable. Escolha enable — o sandbox vale para esta sessão do Copilot e para cada comando de shell que ela executar.
![Copilot CLI slash-command menu listing /sandbox enable and /sandbox disable above the /sandbox [enable|disable] prompt hint](/images/guides/copilot-sandbox-tutorial/copilot-sandbox-tutorial-sandbox-enable-autocomplete.webp "Copilot CLI slash-command menu listing /sandbox enable and /sandbox disable above the /sandbox [enable|disable] prompt hint")
O autocompletar de /sandbox oferecendo enable e disable.Assistir em 0:24 - 3
Confirme que a sessão está em sandbox
O Copilot imprime "Sandboxing has been enabled." e a barra de status passa a mostrar "sandbox enabled" ao lado dos AI Credits. Daí em diante, os comandos do agente rodam dentro do sandbox.
"Sandboxing has been enabled." — a confirmação que você quer ver.Assistir em 0:12
2 · Delimitar o que o sandbox alcança
- 4
Abra /sandbox para moldar a política
Um /sandbox sozinho abre o painel Configure sandbox, guardado no settings.json sob `sandbox`. A aba General decide o que roda lá dentro: comandos de shell, servidores MCP, servidores LSP e o acesso ao chaveiro do macOS para os helpers de credenciais do git e do gh.
A aba General: shell, servidores MCP e LSP, além do acesso ao chaveiro.Assistir em 0:30 - 5
Delimite o sistema de arquivos
A aba Filesystem adiciona seu diretório de trabalho automaticamente aos caminhos de leitura/escrita e pode redefinir permissões quando o sandbox encerra. Caminhos de ferramentas como ~/.nvm e ~/.npm são montados somente leitura — amplie a lista se sua cadeia de ferramentas precisar de mais.
Caminhos somente leitura para nvm e npm, com o diretório de trabalho incluído de série.Assistir em 0:32 - 6
Delimite a rede
A aba Network mostra as três alavancas: permitir internet de saída, permitir a rede local e uma lista Access por host. Se a tarefa não precisa de downloads, aperte isso primeiro.
Política de rede: saída, rede local e lista de permissão por host.Assistir em 0:36 - 7
Programe normalmente — os comandos seguem em sandbox
Trabalhe como de costume. O agente planeja, edita e executa comandos enquanto a barra de status segue mostrando "sandbox enabled". Se um comando precisar de algo que a política nega, o Copilot falha alto em vez de escapar da caixa em silêncio.
Uma migração de SQLAlchemy planejada e executada com "sandbox enabled" na barra de status.Assistir em 0:20
3 · Trabalhar, desligar ou ir para a nuvem
- 8
Volte atrás com /sandbox disable
Precisa de um passo fora da caixa? O /sandbox disable desliga o sandbox — aparece "Sandboxing has been disabled." e o selo de sandbox sai da barra de status. Você pode alternar quantas vezes a tarefa pedir.
"Sandboxing has been disabled." — repare que o selo de sandbox sumiu da barra de status.Assistir em 0:38 - 9
Inicie um sandbox na nuvem com copilot --cloud
Para trabalho mais pesado, inicie o Copilot com a flag --cloud (a demo oficial a combina com --yolo; a documentação do GitHub mostra --cloud --experimental). A sessão roda num ambiente efêmero hospedado pelo GitHub, não na sua máquina.
copilot --cloud --yolo — a sessão inteira está prestes a deixar seu notebook.Assistir em 0:50 - 10
Pegue o link de controle remoto
Quando a sessão remota é provisionada, o Copilot conecta o controle remoto e imprime uma URL github.com/copilot/tasks/... — ctrl+e mostra um código QR. A árvore de trabalho fica em /workspaces/<repo> dentro do sandbox na nuvem.
Controle remoto conectado, com a URL da sessão e o atalho do código QR.Assistir em 1:00 - 11
Deixe-o compilar e testar na nuvem
O agente cria arquivos, instala dependências e roda seus scripts de teste dentro do sandbox na nuvem — aqui ele cria test_auth.py e executa a suíte do backend. Sua máquina fica ociosa enquanto os créditos correm na barra de status.
Testes rodando no sandbox na nuvem, 80,4 AI Credits gastos até agora.Assistir em 1:10 - 12
Acompanhe e retome pelo GitHub.com
A sessão aparece na aba Agents do repositório como Remote CLI session — acompanhe o progresso, mande mensagens pelo navegador e retome depois com copilot --resume, que lista as sessões locais e remotas.
A aba Agents do tailspin-toys acompanhando a sessão na nuvem ao vivo.Assistir em 1:14
Onde moram as configurações: app do Copilot vs CLI do Copilot
O sandbox local existe em duas superfícies, e as configurações de cada uma são definidas separadamente — mudar uma nunca muda a outra.
- 1App do Copilot: desligado por padrão. Abra as configurações do app, selecione o projeto e, em "Sandbox", ative "Sandbox new sessions". A política do projeto descreve o que uma sessão em sandbox pode solicitar.
- 2Política do app: o acesso a arquivos começa com leitura/escrita para o workspace e o diretório atual, com listas de leitura/escrita adicional, somente leitura e negados; a rede cobre internet de saída e rede local; as credenciais cobrem git e GitHub CLI.
- 3CLI do Copilot: o sandbox é experimental — inicie com --experimental (ou rode /experimental on) e use /sandbox enable, /sandbox disable ou o /sandbox sozinho para abrir o painel. As configurações ficam no settings.json sob `sandbox`.
- 4Os comandos com barra dependem do momento: /sandbox on ou /sandbox off durante uma sessão ativa vale só para aquela sessão, já antes de iniciá-la muda o padrão do projeto. Use /restart-session para aplicar mudanças sem perder o histórico.
- 5Sessões na nuvem são outro mundo: as configurações locais não valem para sandboxes na nuvem nem para sessões em host remoto, e o sandbox na nuvem precisa ser ativado por um dono de organização ou empresa antes de aparecer.
A demo de CLI deste guia mostra o caminho mais rápido; a chave por projeto do app é o padrão duradouro depois que você define a política que quer.
Quando o sandbox diz não: falha fechada por design
O sandbox é construído para falhar fechado — se o sistema operacional não consegue impor a política pedida, o comando dá erro em vez de rodar sem sandbox.
- 1Plataforma ou política sem suporte: se a política solicitada não pode ser imposta, o shell do sandbox falha com erro — ele nunca volta silenciosamente a rodar sem sandbox.
- 2"Sandbox unavailable": o app sinaliza o problema e oferece um botão Retry sandbox depois que você corrige a causa.
- 3A escotilha de escape: um aviso "Run outside the sandbox?" pode oferecer cancelar, rodar uma vez fora ou desligar o sandbox para a sessão — "Re-enable sandbox" volta atrás. Isso acaba ao reiniciar e nunca muda os padrões do projeto.
- 4Os donos da empresa podem ter a palavra final: configurações gerenciadas podem bloquear a escotilha de fuga para fora do sandbox, e ali a imposição também falha fechada.
Notas de plataforma: recomenda-se macOS 15+ (Seatbelt); o Linux precisa de bubblewrap 0.5.0+ no PATH além de slirp4netns, util-linux 2.35+, iptables e /dev/net/tun; o Windows usa o nível BaseContainer do ProcessContainer — um caminho negado que não pode ser garantido faz o comando falhar com mensagem unsupported-policy.