> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Isolamento em nível de sistema operacional para sessões do Devin CLI: como a sandbox funciona, filtragem de rede e imposição no Enterprise.

A opção `--sandbox` executa o CLI com isolamento em nível de sistema operacional, aplicando os escopos ativos de permissão de leitura e gravação no próprio sistema operacional e, opcionalmente, restringindo o tráfego de rede.

<div id="how-the-sandbox-works">
  ## Como o sandbox funciona
</div>

Quando o sandbox está ativo:

* Os **caminhos graváveis** são derivados dos escopos de permissão `Write(...)` concedidos, mais o diretório do workspace
* Os **caminhos legíveis** são derivados dos escopos `Read(...)` concedidos (padrões da plataforma, como `/usr/bin`, são sempre legíveis)
* Escopos concedidos no meio da sessão expandem dinamicamente o sandbox para os comandos subsequentes

<Warning>
  Se a resolução do sandbox falhar (por exemplo, se as ferramentas de sandbox não estiverem disponíveis na plataforma do usuário), a CLI **se recusará a iniciar** em vez de ser executada fora do sandbox. Esse comportamento de falha segura se aplica tanto quando o sandbox foi ativado por uma [configuração da equipe](/pt-BR/cli/enterprise/team-settings#sandbox-enforcement) quanto pelo usuário ao passar `--sandbox` diretamente, garantindo que a intenção de segurança nunca seja contornada silenciosamente.

  Causas comuns de falha na resolução do sandbox:

  * **Windows**: o sandbox em nível de SO não tem suporte no Windows no momento. As sessões no Windows falharão imediatamente quando `--sandbox` for passado ou quando a imposição do sandbox for **obrigatória**, inclusive quando a CLI for executada como um servidor ACP dentro de uma IDE (por exemplo, Devin Desktop).
  * **Linux**: o sandbox exige que `bubblewrap` (`bwrap`) e `socat` estejam instalados. As sessões falham imediatamente com instruções de instalação quando eles não estão presentes.
  * **Erros de escopo de permissão**: caminhos inválidos em escopos de permissão que não podem ser resolvidos.
</Warning>

<div id="network-filtering">
  ## Filtragem de rede
</div>

<Warning>
  A filtragem de rede do sandbox está instável no momento. Se você precisar desse recurso, entre em contato com o representante da sua conta para saber a previsão de estabilização.
</Warning>

Configure a filtragem de rede em nível de domínio para o sandbox na [seção `sandbox` do seu arquivo de configuração](/pt-BR/cli/reference/configuration/config-file#sandbox) (apenas na configuração do usuário). Quando `--sandbox` está ativo e a filtragem de domínio está configurada, um proxy de rede gerenciado é iniciado na interface de loopback, e o sandbox restringe todo o tráfego dos processos filhos para passar por ele.

| Opção             | Tipo      | Padrão   | Descrição                                                                                                                                                            |
| ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed_domains` | string\[] | `[]`     | Padrões de domínio permitidos pelo proxy. Quando não estiver vazio, apenas os domínios que corresponderem aos padrões serão permitidos (modo de lista de permissões) |
| `denied_domains`  | string\[] | `[]`     | Padrões de domínio sempre bloqueados. As regras de negação têm precedência sobre as regras de permissão                                                              |
| `network_mode`    | string    | `"full"` | `"full"` permite todos os métodos HTTP; `"limited"` permite apenas GET/HEAD/OPTIONS                                                                                  |

**Sintaxe de padrão de domínio:**

| Padrão           | Correspondência                          |
| ---------------- | ---------------------------------------- |
| `example.com`    | Apenas correspondência exata             |
| `*.example.com`  | Qualquer subdomínio (não o domínio raiz) |
| `**.example.com` | Domínio raiz e qualquer subdomínio       |

**Exemplo:**

```json theme={null}
{
  "sandbox": {
    "allowed_domains": [
      "github.com",
      "**.npmjs.org",
      "**.crates.io",
      "**.pypi.org"
    ],
    "denied_domains": ["evil.example.com"],
    "network_mode": "full"
  }
}
```

<Note>
  A filtragem de domínio se aplica quando o sandbox está ativo (`--sandbox`). Sem `--sandbox`, a seção do sandbox é ignorada.
</Note>

<div id="excluded-commands">
  ## Comandos excluídos
</div>

Às vezes, um comando específico precisa ser executado *fora* do sandbox — por exemplo, comandos `git` que precisam acessar credenciais ou hooks bloqueados pelo sandbox. A seção de configuração `sandbox.excluded` permite excluir do isolamento do sandbox os comandos correspondentes, usando a mesma sintaxe de regra `Exec(...)` de [permissão](/pt-BR/cli/reference/permissions):

| Opção            | Tipo      | Descrição                                                                                    |
| ---------------- | --------- | -------------------------------------------------------------------------------------------- |
| `excluded.allow` | string\[] | Comandos correspondentes são executados fora do sandbox automaticamente                      |
| `excluded.ask`   | string\[] | Comandos correspondentes são executados fora do sandbox após o usuário aprovar a solicitação |
| `excluded.deny`  | string\[] | Comandos correspondentes nunca são excluídos — eles sempre permanecem dentro do sandbox      |

**Exemplo:**

```json theme={null}
{
  "sandbox": {
    "excluded": {
      "allow": ["Exec(git status *)"],
      "ask": ["Exec(git push *)"],
      "deny": ["Exec(git tag *)"]
    }
  }
}
```

**Resolução de regras:** para cada comando, a regra correspondente mais específica prevalece dentro de uma origem (por exemplo, `Exec(git push *)` prevalece sobre `Exec(git *)`), e, quando tanto a configuração do usuário quanto as [Configurações da equipe](#enterprise-excluded-commands) se aplicam, prevalece a decisão mais restritiva (`deny` > `ask` > `allow`). Comandos sem nenhuma regra correspondente — inclusive quando `sandbox.excluded` não está configurado — sempre são executados dentro do sandbox.

<Note>
  * Somente regras `Exec(...)` têm suporte em `sandbox.excluded`; qualquer outro tipo de regra (por exemplo, `Read(...)`, `Write(...)`) é ignorado com um aviso.
  * A exclusão é fail-closed: se um comando não puder ser resolvido com segurança (por exemplo, se não puder ser analisado), ele permanece dentro do sandbox.
  * As exclusões se aplicam ao caminho de execução padrão de cada comando. Comandos executados por meio de um shell PTY persistente (sessões interativas ou quando `pty_for_noninteractive_exec` está ativado) sempre permanecem dentro do sandbox.
</Note>

<div id="enterprise-enforcement">
  ## Aplicação obrigatória no Enterprise
</div>

Os admins do Enterprise podem controlar o comportamento do sandbox em toda a organização por meio de [Configurações da equipe](/pt-BR/cli/enterprise/team-settings#sandbox-enforcement).

<div id="sandbox-enforcement-mode">
  ### Modo de imposição do sandbox
</div>

Defina o nível de imposição da flag `--sandbox` em toda a sua organização:

* **Opcional** (padrão) — Os usuários escolhem se querem informar `--sandbox`. Sem imposição.
* **Obrigatório** — A flag `--sandbox` é aplicada a todos os usuários, mesmo que eles não a informem na linha de comando. Todas as sessões de CLI são executadas com sandbox de sistema de arquivos em nível de SO, que aplica escopos de permissão de leitura/gravação.

No futuro, um modo **Strict** poderá restringir totalmente a configuração do sandbox, impedindo que os usuários modifiquem suas configurações.

<Warning>
  Certifique-se de que todas as máquinas de destino estejam provisionadas antes de definir o modo de imposição do sandbox como **Obrigatório** em toda a sua organização. Se algum usuário usar Windows, não conseguirá executar a CLI até que o sandbox em nível de SO tenha suporte no Windows ou que a política seja flexibilizada para **Opcional**.
</Warning>

<div id="enterprise-domain-filtering">
  ### Filtragem de domínios no Enterprise
</div>

Os administradores também podem configurar listas de permissões e listas de bloqueio de domínios para toda a organização:

* **Lista de permissões de domínios** — Quando definida, **somente** os domínios desta lista podem ser acessados pelo proxy de rede do sandbox. Esta lista é **definitiva**: ela substitui completamente qualquer `allowed_domains` configurado pelo usuário. Os usuários não podem adicionar domínios extras para contornar as restrições do administrador.
* **Lista de bloqueio de domínios** — Domínios que são sempre bloqueados. Os domínios bloqueados no Enterprise são **aditivos**: eles são mesclados com o `denied_domains` local do usuário, tornando a lista combinada mais restritiva.

**Como as listas de domínios do Enterprise e do usuário interagem:**

| Cenário                                  | Configuração do Enterprise        | Configuração do usuário           | Resultado efetivo                                                            |
| ---------------------------------------- | --------------------------------- | --------------------------------- | ---------------------------------------------------------------------------- |
| Administrador define lista de permissões | `allowed_domains: ["github.com"]` | `allowed_domains: ["npmjs.org"]`  | Somente `github.com` é permitido (o Enterprise substitui a lista do usuário) |
| Administrador define lista de bloqueio   | `denied_domains: ["evil.com"]`    | `denied_domains: ["risky.io"]`    | Tanto `evil.com` quanto `risky.io` são bloqueados (mesclados)                |
| Sem lista de permissões do administrador | `allowed_domains: []`             | `allowed_domains: ["github.com"]` | A lista de permissões do usuário é usada                                     |

<Note>
  Como o `denied_domains` local do usuário é preservado e mesclado de forma aditiva, o usuário pode bloquear um domínio que aparece na lista de permissões do Enterprise. Isso é intencional: o efeito combinado é sempre mais restritivo, nunca menos. Se isso causar problemas de acesso, o usuário deve remover a entrada conflitante da configuração local.
</Note>

<div id="enterprise-excluded-commands">
  ### Comandos excluídos no Enterprise
</div>

Os administradores também podem definir regras de [comandos excluídos](#excluded-commands) para toda a organização nas Configurações da equipe:

* **Excluded allow / ask** — regras `Exec(...)` para comandos que podem ser executados fora do sandbox em toda a organização, automaticamente ou após uma confirmação.
* **Excluded deny** — regras `Exec(...)` para comandos que nunca devem ser executados fora do sandbox. Um `deny` da equipe tem precedência sobre qualquer `allow` ou `ask` em nível de usuário para comandos correspondentes, então os usuários não podem excluir comandos que seus administradores restringiram.

As regras da equipe e do usuário são avaliadas em conjunto: a regra correspondente mais específica prevalece dentro de cada origem, e a decisão mais restritiva prevalece entre as origens (`deny` > `ask` > `allow`).

**Exemplo: bloquear todas as exclusões, exceto `gh`.** Um `deny` curinga com uma exceção `allow` mantém todos os comandos dentro do sandbox, exceto `gh`, independentemente do que os usuários configurarem localmente. Esses valores vão na configuração de comandos excluídos das Configurações da equipe (não no arquivo de configuração do usuário, portanto não há uma chave `sandbox` de nível superior):

```json theme={null}
{
  "excluded": {
    "deny": ["Exec(**)"],
    "allow": ["Exec(gh *)"]
  }
}
```

Como a regra mais específica `Exec(gh *)` prevalece sobre o curinga `Exec(**)`, os comandos `gh` são executados fora do sandbox, enquanto todo o restante permanece dentro — e o curinga `deny` no nível da equipe se sobrepõe a quaisquer regras `allow` ou `ask` no nível do usuário para outros comandos.

<div id="further-reading">
  ## Leitura adicional
</div>

* [Configurações da equipe](/pt-BR/cli/enterprise/team-settings#sandbox-enforcement) — imposição de sandbox no Enterprise e filtragem de domínios
* [Referência do arquivo de configuração](/pt-BR/cli/reference/configuration/config-file#sandbox) — a seção de configuração `sandbox` em nível de usuário
* [Permissões](/pt-BR/cli/reference/permissions) — escopos de permissão que determinam a resolução de caminhos do sandbox