Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Modo sandbox

Status: Ativo Escopo: estado atual Última revisão: 2026-08-23 Responsável: ax-code runtime

O AX Code inclui um sandbox de execução embutido que pode restringir o que o agente de IA faz no seu sistema. Por padrão, o AX Code inicia em acesso total, com o sandbox desligado, então gravações no sistema de arquivos e acesso à rede ficam sem restrição. Ative workspace-write ou read-only antes de trabalhar com repositórios não confiáveis ou de executar tarefas sem supervisão.

Aviso de segurança: full-access não é uma fronteira de segurança. O agente pode modificar arquivos fora do workspace, gravar .git/ e .ax-code/, executar comandos de shell sem restrição e acessar a rede.

Início rápido

Alterne o sandbox pela TUI:

• Digite /sandbox no prompt, ou
• Pressione Ctrl+P e busque “sandbox”

A barra de status mostra o estado atual:

• sandbox ligado (verde) — agente confinado ao workspace
• sandbox desligado (vermelho) — sem restrições

O ajuste persiste entre sessões em ax-code.json.

O que muda

Configuração

Fonte da verdade

Esta página resume o comportamento visto pelo usuário. Quando o comportamento mudar, confira a documentação contra:

• packages/ax-code/src/isolation/index.ts para resolução de modo, caminhos protegidos, checagens de rede, de gravação e de bash, e IsolationDeniedError.
• packages/ax-code/src/config/schema.ts para a forma da configuração, os padrões e as descrições.
• packages/ax-code/src/server/routes/isolation.ts para o comportamento do interruptor em runtime e a persistência.
• packages/ax-code/test/isolation/isolation.test.ts e packages/ax-code/test/tool/bash.test.ts para o comportamento esperado de imposição.

Mantenha as afirmações duplicadas no README da raiz curtas e aponte para cá nos detalhes.

Alternar pela TUI

Use /sandbox ou a paleta de comandos (Ctrl+P → “Ligar ou desligar o sandbox”). A mudança vale na hora e é salva no ax-code.json do projeto.

Marca da CLI

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Variável de ambiente

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Arquivo de configuração

Em ax-code.json:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Precedência

Marca da CLI > variável de ambiente > arquivo de configuração > padrão (full-access)

Quando uma substituição da CLI ou do ambiente está ativa, a TUI informa esse modo efetivo. Um interruptor /sandbox pode salvar a preferência do projeto, mas a substituição de precedência mais alta permanece ativa até ser removida (em geral, na reinicialização).

Modos de isolamento

Caminhos protegidos

No modo workspace-write, estes caminhos ficam sempre protegidos contra gravação:

• .git/ — evita corrupção acidental do estado do git
• .ax-code/ — evita adulteração de configuração e de plugin

Acrescente caminhos protegidos personalizados na configuração:

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Acesso à rede

A rede fica desativada por padrão nos modos workspace-write e read-only. Ferramentas afetadas:

• webfetch — bloqueada
• websearch — bloqueada
• codesearch — bloqueada
• bash — clientes só de rede (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) são bloqueados

Limitação: o bloqueio de rede em bash é da camada da aplicação e cobre os clientes de rede dedicados acima. Ele não intercepta ferramentas de uso duplo que também funcionam offline (git, npm/pnpm/yarn, pip, go, interpretadores de linguagem como python/node), porque as invocações offline delas não podem ser distinguidas de forma estática, e bloqueá-las quebraria fluxos comuns. Um isolamento de rede verdadeiro e exaustivo exige controles no nível do sistema operacional, que este sandbox não fornece. Quando um cliente negado é atingido, o agente pede uma elevação única.

Para permitir a rede e manter as restrições de gravação:

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Backend de isolamento (aplicação e sistema operacional)

macOS: perfis Seatbelt por sandbox-exec (gravação limitada ao workspace ou à worktree, rede negada quando network: false).
Linux: bubblewrap (bwrap) quando instalado (--unshare-net quando a rede está desativada, workspace montado com ligação em leitura e gravação).
Windows: somente a camada da aplicação, hoje.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Veja SECURITY.md para o modelo de ameaça.

Permissões e hooks controlados pelo repositório

Arquivos de projeto não são confiáveis por padrão. Regras de permissão em ax-code.json, .ax-code/policy.json e definições de agente ou de modo do projeto podem apertar o acesso com deny, mas concessões allow/ask controladas pelo repositório são ignoradas. Comandos do projeto não podem ativar expansão de shell. .ax-code/hooks.json, .ax-code/plugin/ e plugins configurados pelo projeto não são executados.

Configuração de projeto não confiável também não pode selecionar um shell personalizado, um LSP ou formatador executável, um pacote de provedor ou endpoint de API, variáveis de ambiente de credencial de provedor, uma origem externa de skill ou um caminho de instrução fora da worktree. Caminhos relativos seguros de instrução e substituições embutidas não executáveis continuam disponíveis. Servidores MCP usam um fluxo separado de aprovação com impressão digital, descrito em Integrações MCP.

Depois de revisar a configuração controlada pelo repositório, o usuário pode optar, fora do repositório, pelo processo atual:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

O interruptor só de ambiente impede que um checkout se declare confiável.

Como a imposição funciona

A imposição do sandbox é sempre da camada da aplicação, conferida em cada invocação de ferramenta. Quando backend é os ou auto e a plataforma aceita, o bash é adicionalmente envolvido num sandbox do kernel.

Quando uma ferramenta viola o isolamento, ela lança um IsolationDeniedError com uma mensagem clara que explica o que foi bloqueado e por quê.