Se você preferir não usar --shell-install, adicione a linha você mesmo:```bash

zsh / bash

eval "$(cplt --shell-setup --agent opencode)"

fish

alias opencode 'cplt --agent opencode'

O mesmo padrão que mise, direnv e starship usam.
</details>

**Por que cada alias nomeia seu agente.** `alias opencode=cplt` não faria o que parece. O `cplt` simplesmente escolhe seu agente a partir de `--agent`, depois do arquivo de configuração, e então do que encontrar no PATH — e a detecção do PATH prefere `copilot`. Digitar `opencode` acabaria isolando o Copilot, sem nada na tela para avisar. O alias passa `--agent` para que o comando que você digita seja o agente que você obtém.

**Por que um alias em vez de um symlink?** O cplt e o Copilot CLI instalam no mesmo diretório bin do Homebrew (`/opt/homebrew/bin/`), e apenas um arquivo chamado `copilot` pode existir lá, então um symlink entraria em conflito. Um alias contorna isso. O binário real `copilot` permanece no PATH onde o cplt pode encontrá-lo e envolvê-lo, e o alias redireciona seu comando.

> **Nota:** o cplt se recusa a aninhar. Se ele detectar que já está sendo executado dentro de um sandbox (através da variável de ambiente `__CPLT_WRAPPED`), ele não iniciará novamente. Subcomandos somente leitura, como `--print-profile` e `cplt doctor`, ainda funcionam dentro de um sandbox existente.

## Uso```
cplt [OPTIONS] [-- <AGENT_ARGS>...]

Tudo depois de -- vai direto para o processo do agente (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh ou shell).

Presets de política

Um preset define uma linha de base para os cinco principais toggles de sandbox com uma flag em vez de uma lista delas. Flags individuais ainda prevalecem sobre o preset, então --preset permissive --no-allow-tmp-exec faz o que diz. Também configurável como [sandbox] preset = "..." no config.

Matriz completa de presets e ordem de resolução: docs/configuration.md.

Acesso a arquivos

O diretório do projeto é o workspace gravável, mais uma allowlist estreita necessária para autenticação, runtime e ferramentas (veja a tabela acima). O kernel bloqueia todo o resto, incluindo chaves SSH e credenciais de nuvem.

Variáveis de ambiente

cplt sanitiza o ambiente filho por padrão. Apenas variáveis seguras passam, e credenciais de nuvem, URLs de banco de dados e tokens de pacotes são removidos. Também injeta variáveis de hardening que bloqueiam scripts de ciclo de vida do npm/yarn/pnpm (hooks postinstall, o vetor de ataque de cadeia de suprimentos número um), desabilitam assinatura de commit e tag do git (já que ~/.ssh e ~/.gnupg são inacessíveis dentro do sandbox), e optam por não participar de telemetria de ferramentas de desenvolvimento (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1, e outros).

O que passa:

Allowlist de prefixo com proteção de sufixo secreto. Uma variável que corresponde a um prefixo permitido como COPILOT_* ou YARN_* ainda é descartada se terminar em um sufixo portador de segredo: _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD ou _CREDENTIALS. Então COPILOT_DEBUG passa e COPILOT_API_KEY não.

Sempre bloqueados: AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, variáveis do Docker, tokens de CI, e qualquer coisa que não esteja na allowlist.

Toggles de sandbox

Runtimes suportados

cplt auto-descobre ferramentas instaladas e escreve regras de sandbox para corresponder. Geralmente apenas diretórios que existem no disco recebem regras, então não há caminhos fantasma. No macOS, diretórios de aplicativos graváveis são incluídos quando descobertos mesmo se ainda não existirem, para que possam ser criados no primeiro uso. O Linux não pode permitir escrita em um caminho inexistente, então a criação precisa acontecer fora do sandbox lá.

Execute cplt doctor para ver se o cplt funcionará aqui para o seu agente, e cplt doctor --verbose para tudo que ele detectou na sua máquina.

Depuração

Flags de sessão

Estas se traduzem nas próprias flags de sessão do agente, então você não precisa de um separador --.

--continue e --resume também são mapeados para OpenCode, Antigravity e Claude Code:

¹ Nem OpenCode nem Antigravity têm um seletor de sessão interativo, então um --resume sozinho significa "continuar a última sessão". Claude Code tem um, então mapeia diretamente.

--remote e --name são exclusivos do Copilot. Pi e modo shell não recebem tradução alguma, então todas as quatro flags são descartadas para eles. Auto-resume é um mecanismo separado: quando você invoca cplt sem args de pass-through e sem flags de sessão, ele anexa --resume para você, e isso se aplica apenas ao Copilot.

Combine-os com flags de sandbox e args de pass-through --:```bash cplt --resume=my-task # resume by name cplt --remote --name my-task -- -p "fix tests" # remote + named + prompt

### Agentes

Escolha um com `--agent <name>`, ou torne-o o padrão com `cplt config set sandbox.agent <name>`. Copilot, OpenCode e Antigravity são detectados automaticamente a partir do `PATH` nessa ordem quando você não nomeia um.

| Agente | Valor de `--agent` | Detectado automaticamente | Autenticação |
| --- | --- | --- | --- |
| GitHub Copilot CLI | `copilot` | sim, prioridade 1 | Token do GitHub, do Keychain ou do `gh` |
| [OpenCode](https://opencode.ai/) | `opencode` | sim, prioridade 2 | Assinatura do Copilot via `/connect`, ou `--pass-env ANTHROPIC_API_KEY` |
| [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) | `antigravity`, aliases `agy` e `agi` | sim, prioridade 3 | Google OAuth no navegador |
| [Pi](https://github.com/earendil-works/pi) | `pi` | não | `--pass-env ANTHROPIC_API_KEY` e similares |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude`, aliases `cc` e `claude-code` | não | OAuth de assinatura em `~/.claude` ou no Keychain, `CLAUDE_CODE_OAUTH_TOKEN` (descarta a concessão do Keychain), ou `--pass-env ANTHROPIC_API_KEY` |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh`, aliases `deepseek` e `deepseek-harness` | não | `--pass-env DEEPSEEK_API_KEY`, ou `$DSH_HOME/.env` (`~/.dsh/.env`) |
| Seu shell | `shell` | não | nenhuma |

- **Pi, Claude Code, goose e DeepSeek Harness nunca são detectados automaticamente.** `pi` e `dsh` são nomes de binários genéricos que podem colidir com outra coisa na sua máquina, e o Claude Code precisa ser escolhido de propósito.
- **Chaves de API de terceiros são opt-in.** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN` e as variáveis de roteamento Bedrock/Vertex (`CLAUDE_CODE_USE_BEDROCK`, `AWS_BEARER_TOKEN_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `ANTHROPIC_VERTEX_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`) nunca passam, a menos que você as nomeie com `--pass-env`.
- **Autenticação por assinatura não precisa de variável de ambiente.** O fluxo de dispositivo `/connect` do OpenCode armazena seu token em `~/.local/share/opencode/auth.json`, e o token OAuth do Claude Code fica em `~/.claude` (`.credentials.json` no Linux) ou no Keychain do macOS. Ambos são acessíveis dentro do sandbox, então o cplt não fica insistindo sobre uma chave de API ausente para nenhum dos dois.
- **Fluxos OAuth no navegador precisam de `--allow-browser`** quando aparece um prompt de login. Isso cobre o Antigravity; todos os outros agentes aqui usam um fluxo de dispositivo que imprime um código e uma URL e não precisa de navegador. A flag permite que o agente inicie qualquer aplicação fora do sandbox e não pode ser restringida a URLs, então ative-a para o login e desative-a novamente — veja a [tabela de flags](#sandbox-toggles) e [docs/security.md](https://github.com/navikt/cplt/blob/main/docs/security.md#--allow-browser-is-a-sandbox-escape-and-cannot-be-scoped).
- **A atualização automática do Claude Code está desabilitada** com `DISABLE_AUTOUPDATER=1`. O Claude Code não tem uma flag `--no-auto-update`, a auto-atualização dentro do sandbox é um vetor de persistência, e falharia de qualquer forma contra caminhos de instalação somente leitura.
- **`CLAUDE_CONFIG_DIR` é respeitado.** Quando definido, o cplt concede esse diretório em vez de `~/.claude` e repassa a variável, então uma raiz de configuração realocada continua funcionando.
- O OpenCode é [um cliente Copilot oficialmente suportado](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/), então sua assinatura existente do Copilot funciona com `/connect` dentro do OpenCode.

Diretórios de configuração por agente, uso do Keychain, permissões de execução e isolamento de ambiente estão em [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md#supported-agents).

### Suporte ao goose

O cplt pode colocar em sandbox o [goose](https://github.com/aaif-goose/goose), o agente de IA de código aberto (binário `goose`). Verificado com o goose 1.48.0.```bash
# Run goose (must be explicit — not auto-detected)
cplt --agent goose

# goose is provider-agnostic — pass your provider's API key
cplt --agent goose --pass-env ANTHROPIC_API_KEY
cplt --agent goose --pass-env OPENAI_API_KEY

# Skip the keyring entirely: keep the key in the environment
GOOSE_DISABLE_KEYRING=1 cplt --agent goose --pass-env OPENAI_API_KEY --pass-env GOOSE_DISABLE_KEYRING

# Set goose as your default agent
cplt config set sandbox.agent goose

Notas de segurança para goose:

• Não é detectado automaticamente: selecione explicitamente com --agent goose ou defina sandbox.agent = "goose" na config
• Agnóstico em relação ao provedor: o goose encaminha o tráfego do modelo para um provedor configurado pelo usuário (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Chaves de provedores comuns (ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY, DATABRICKS_HOST/DATABRICKS_TOKEN, GROQ_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, AWS_BEARER_TOKEN_BEDROCK) são reconhecidas como dicas de autenticação e devem ser passadas via --pass-env. O goose lê , não . Qualquer provedor fora desse subconjunto ainda funciona: nomeie sua variável com

Suporte ao DeepSeek Harness

O cplt pode colocar em sandbox o DeepSeek Harness (binário dsh), o harness de agente orientado a plugins da DeepSeek. O upstream o disponibiliza como developer preview e seu próprio SAFETY.md diz para não confiar em seus controles como a única fronteira, que é exatamente o caso para o qual o cplt existe.```bash

Run DSH (must be explicit — not auto-detected)

cplt --agent dsh

Pass the API key, or keep it in $DSH_HOME/.env

cplt --agent dsh --pass-env DEEPSEEK_API_KEY

Set DSH as your default agent

cplt config set sandbox.agent dsh

**Notas de segurança para DSH:**
- **Não é detetado automaticamente**: selecione-o com `--agent dsh` (aliases `deepseek`, `deepseek-harness`) ou defina `sandbox.agent = "dsh"`. `dsh` é um nome de comando curto e genérico que pode pertencer a outra coisa na sua máquina
- **Desative o sandbox do próprio DSH dentro do cplt**: o DSH envolve cada chamada de shell e de ferramenta de ficheiro no seu próprio sandbox de processo — Seatbelt no macOS, bwrap ou Landlock no Linux. Nenhum deles se aninha dentro do cplt. O macOS não suporta chamadas `sandbox-exec` aninhadas (a mesma limitação que faz o cplt desativar o sandbox interno do Gradle, ver [Limitations](#limitations)), e o bwrap constrói o seu namespace com `unshare`, que o filtro seccomp do cplt nega. O cplt é a fronteira de imposição de qualquer forma, por isso escolha o preset de permissões `danger-full-access` fornecido pelo DSH para sessões em sandbox. Deixe o runner interno ativo e as chamadas de ferramentas falham com um erro do sandbox runner em vez de um erro de tarefa
- **Uma raiz home, e o cplt segue a substituição**: o DSH mantém sessões, definições, cache e perfis sob `$DSH_HOME` (`~/.dsh` por predefinição). `DSH_HOME` está na lista de permissões de env, por isso o processo filho resolve a mesma raiz que o cplt concede. Um valor que aponte para uma raiz de sistema ou para o seu diretório home é recusado antes do lançamento, o mesmo veto pelo qual `CLAUDE_CONFIG_DIR` passa
- **Guarda de persistência no host**: `$DSH_HOME/cordis.patch.yml`, o overlay ao nível do home que o Loader lê no arranque, tem escrita negada. `$DSH_HOME/profiles/` permanece gravável porque o DSH reescreve a raiz de inclusão `cordis.yml` de cada perfil a cada arranque, por isso um `cordis.patch.yml` por perfil e plugins instalados são um residual documentado — faça edições de perfil e de `dsh plugin` fora do cplt, e lance sempre `dsh` através do cplt para que qualquer coisa plantada continue a correr em sandbox
- **Domínios predefinidos**: apenas `deepseek.com`. O adaptador `dsh-llm-deepseek` fornecido usa por predefinição `https://api.deepseek.com`. Aponte `DEEPSEEK_BASE_URL` para um gateway e terá de adicionar o domínio desse gateway via `allowed_domains`
- **Autenticação**: passe a chave com `--pass-env DEEPSEEK_API_KEY`, ou mantenha-a em `$DSH_HOME/.env`. Uma chave guardada através da própria UI de modelos do DSH fica em `$DSH_HOME/.credentials.yaml`, dentro da mesma raiz gravável. O Keychain do macOS é negado, por isso `git push` sobre HTTPS precisa do token do `gh` em `hosts.yml` ou de `--pass-env GH_TOKEN`

### Modo shell

Execute uma shell simples em sandbox sem agente de IA e com as mesmas restrições. Útil para testar ferramentas de build, depurar problemas de sandbox, ou simplesmente trabalhar com cuidado à mão.```bash
# Interactive sandboxed shell (uses $SHELL: fish, zsh, bash)
cplt --agent shell

# Inspect what's allowed without entering the shell
cplt --agent shell --print-profile

As mesmas regras de negação por padrão se aplicam: isolamento do sistema de arquivos, restrições de rede, sanitização de env. Os diretórios de configuração do shell (variáveis e histórico do fish, histórico do zsh) permanecem graváveis.

Para um único comando, cplt exec é mais limpo do que cplt --agent shell -- -c 'cmd'.

Modo exec

Execute qualquer comando dentro do sandbox sem iniciar um agente. Sem banner de inicialização, sem prompt de confirmação, portanto é adequado para scripts, pipes e aliases de shell.```bash

Sandbox a single command

cplt exec -- npm install cplt exec -- make build cplt exec -- go test ./...

Compound commands via $SHELL -c

cplt exec -c "npm install && npm test"

Pass sandbox flags as usual

cplt exec --allow-lifecycle-scripts -- npm install cplt exec --project-dir /path/to/repo -- make build cplt exec --with-proxy -- curl https://example.com

Shell aliases for sandboxed tools

alias npm="cplt exec -- npm" alias node="cplt exec -- node" alias python="cplt exec -- python"

Todas as flags de nível superior do `cplt` se aplicam: `--project-dir`, `--allow-read`, `--deny-path`, `--with-proxy`, `--pass-env` e o restante. Adicione `--no-quiet` para ver o resumo completo da configuração do sandbox antes da execução do comando.

### Exemplos```bash
# The common case: Copilot in the sandbox
cplt -- -p "fix the tests"

# Sessions
cplt --resume                                   # pick one interactively
cplt --resume=my-refactor                       # by name
cplt --continue                                 # most recent in this directory
cplt --remote --name my-task -- -p "fix tests"  # named remote session

# Check the environment before the first run
cplt doctor

# Let Copilot read a shared library directory
cplt --allow-read ~/shared-libs -- -p "use shared-libs"

# Block a path you don't want Copilot to see
cplt --deny-path ~/.config/gh -- -p "refactor auth"

# Extra outbound port, e.g. an external API
cplt --allow-port 8443 -- -p "test the API"

# Localhost for MCP servers or dev servers
cplt --allow-localhost 3000 --allow-localhost 8080 -- -p "use the MCP server"

# All of localhost, needed by Next.js/Turbopack and Vite builds
cplt --allow-localhost-any -- -p "fix the build"

# Pass specific env vars through
cplt --pass-env MY_CUSTOM_VAR --pass-env ANOTHER_VAR -- -p "run with custom config"

# Inherit the full environment (dangerous, debugging only)
cplt --inherit-env -- -p "debug the build"

# Network
cplt --no-proxy -- -p "fix the tests"                    # proxy is on by default
cplt --blocked-domains ./blocked-domains.txt -- -p "refactor"
cplt --allow-private-domain intern.nav.no -- -p "use mcp-onboarding"

# Non-interactive / CI (skip the confirmation prompt)
cplt --yes -- -p "fix the tests"

# Inspect and debug the sandbox itself
cplt --print-profile
cplt --show-denials -- -p "fix the tests"

Configuração

A configuração acontece em dois níveis: global, para preferências do desenvolvedor, e por repositório, para políticas da equipe.```bash

Browse and change settings interactively

cplt settings

Set global preferences

cplt config set sandbox.quiet true cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt" cplt config set git_guard.mode warn # observe pushes instead of blocking them cplt config set gh_guard.enabled false # opt out of the gh guard entirely

Set per-repo policy (committed to .cplt.toml)

cplt config set --repo sandbox.allow_jvm_attach true cplt config set --repo deny.paths "~/secrets"

Inspect

cplt config show # effective config (file + defaults) cplt config explain # every key with its description

`cplt settings` é o editor interativo, com visualizações Effective, Global e Repository, pesquisa, alterações preparadas e uma confirmação explícita antes de guardar qualquer coisa sensível à segurança. `cplt config` mantém-se a interface não interativa estável para scripts e CI. As propostas de repositório continuam a ser submetidas e aprovadas separadamente com `cplt trust`. O editor nunca as submete nem aprova automaticamente.

A precedência segue as flags da CLI, depois o ficheiro de configuração global em `~/.config/cplt/config.toml`, e depois os valores predefinidos incorporados. A configuração por repositório em `.cplt.toml` é uma camada separada em vez de um degrau nessa escada: `[deny]` restringe incondicionalmente, e as permissões aprovadas são apenas aditivas, pelo que um repositório pode ativar uma funcionalidade mas nunca pode desativar algo definido por uma flag da CLI ou pela configuração global.

Um `.cplt.toml` na raiz do repositório contém a política da equipa:```toml
[deny]                    # Applied automatically, no opt-in needed
paths = ["~/secrets", "~/.vault-token"]
env = ["VAULT_TOKEN", "DATABASE_URL"]

[propose]                 # Requires developer approval (cplt trust accept)
gh_guard = true
git_push_prevention = true
allow_jvm_attach = true
allow_docker = true

[propose.allow]
ports = [5432]
localhost = [3000]
socket = ["/var/run/docker.sock"]

O cplt lê-o a partir do git HEAD, pelo que o agente não pode adulterar a sua própria política a meio da sessão, e as aprovações de confiança ficam fixadas ao conteúdo do ficheiro. Um .cplt.toml não commitado não concede nada até ser commitado, embora as suas chaves [deny] continuem a aplicar-se. Em CI e scripts, onde ninguém pode responder a um prompt, --accept-repo-config aprova as propostas do ficheiro commitado para essa única execução sem persistir qualquer confiança. O cplt init escreve um por ti ao detetar as ferramentas do projeto:```bash cplt init # preview detected permissions cplt init --write # write .cplt.toml to disk cplt init --quiet # output only TOML (pipe-friendly) cplt init --global # generate a personal ~/.config/cplt/config.toml

Ele conhece JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress, e segredos de ambiente a partir de `.env.example`. Permissões perigosas saem do gerador com um aviso de risco anexado. `--global` olha para coisas ao nível da máquina: navegadores Playwright, assinatura GPG, credenciais de registry, agentes alternativos.

Algumas chaves são apenas globais e rejeitadas de `.cplt.toml` porque são específicas da máquina ou uma preferência local: `sandbox.agent`, `sandbox.quiet`, `sandbox.yes`, `sandbox.validate`, `sandbox.scratch_dir`, `sandbox.pass_env`, `sandbox.inherit_env`, `sandbox.allow_cache_exec`, `sandbox.allow_cache_exec_any`, `proxy.enabled`, `proxy.port`, `proxy.log_file`, `proxy.log_level`, `proxy.blocked_domains`, `proxy.allowed_domains`, e todas as chaves `[gh_guard]` e `[git_guard]`.

Detalhes completos, incluindo o modelo de confiança, regras de expansão de caminhos, e a referência completa do ficheiro de configuração: [docs/configuration.md](https://github.com/navikt/cplt/blob/main/docs/configuration.md).

## Arquitetura```
┌──────────────────────────────────┐
│  cplt (Rust binary)              │
│  ┌───────────┐  ┌─────────────┐  │
│  │ Policy    │  │ CONNECT     │  │
│  │ Generator │  │ Proxy       │  │
│  └─────┬─────┘  │ (optional)  │  │
│        │        └─────────────┘  │
│        ▼                         │
│  ┌─────────────┬────────────┐    │
│  │   macOS     │   Linux    │    │
│  │  Seatbelt   │  Landlock  │    │
│  │  sandbox-   │  + seccomp │    │
│  │  exec       │  pre_exec  │    │
│  └─────────────┴────────────┘    │
│        │                         │
│        ▼                         │
│  copilot (sandboxed)             │
│  ├── All child processes         │
│  ├── Cannot read ~/.ssh          │
│  ├── Network port-restricted     │
│  ├── SSH agent blocked           │
│  └── Filesystem = primary ctrl   │
└──────────────────────────────────┘

O modelo de segurança é um sistema de arquivos deny-by-default com imposição pelo kernel. No macOS, e no Linux com kernel 6.7+ (Landlock ABI v4), a rede é restrita à porta 443 por padrão, com --allow-port para extras. Em kernels Linux mais antigos, o proxy CONNECT fornece essa restrição, razão pela qual está habilitado por padrão. O acesso ao agente SSH e a saída para localhost são bloqueados no kernel no macOS. No Linux, nenhum dos dois é: regras Landlock baseadas em porta não conseguem distinguir localhost de um host remoto, e o connect() de socket unix não é controlado pelo Landlock abaixo do kernel 7.1, então, além dos sockets que o bubblewrap mascara, o SSH_AUTH_SOCK retido é a única coisa entre o agente e suas chaves carregadas. O gerador de perfil descobre seu ambiente (cplt doctor --verbose mostra os mesmos resultados de sondagem) e emite regras apenas para diretórios de ferramentas que realmente existem no disco. Menos regras, sandbox mais restrita.

• macOS: um perfil Seatbelt/SBPL é gerado e entregue ao sandbox-exec
• Linux: regras Landlock LSM mais um filtro seccomp-BPF, aplicados via pre_exec (kernel 5.13+, filtragem de porta TCP no 6.7+)

Internos e layout de módulos: docs/architecture.md. Modelo de ameaças, camadas de defesa e lacunas honestas: SECURITY.md.

Segurança

Um binário, dependências mínimas, sem serviços em tempo de execução, sem telemetria. Três camadas de defesa, com limites claros entre elas:

Contra o que o cplt protege:

• Exfiltração de segredos (chaves SSH, credenciais de nuvem, arquivos .env): bloqueado pelo kernel
• Execução não autorizada de código a partir de diretórios temporários: bloqueado pelo kernel
• Persistência via binários em diretórios de cache: bloqueado pelo kernel, já que esses diretórios têm exec negado
• Persistência via git hooks no projeto: .git/hooks tem escrita negada no kernel no macOS. No Linux, com Landlock e sem Bubblewrap, permanece gravável, e o próprio git do lado pai do cplt então é executado com core.hooksPath=/dev/null, de modo que nunca executa um hook plantado, embora um git que você mesmo execute ainda o fará
• Persistência via diretórios de ferramentas de gerenciadores de pacotes que são simultaneamente graváveis e executáveis (shims do mise, PNPM_HOME, ~/.deno/bin, ~/.bun/bin): a escrita é concedida ali para que pnpm add -g e similares funcionem dentro da sandbox, então um agente pode deixar um binário para trás que um shell posterior pegará do seu PATH
• Um binário plantado sequestrando o agente que o cplt lança: no lançamento e na auditoria, o cplt resolve os auxiliares que ele mesmo executa (, , , , e o do qual lê um token) a partir de diretórios fixos do sistema em vez do , mas o próprio binário do agente é executado de onde quer que tenha sido descoberto, o que, para uma instalação npm-global, geralmente fica sob uma árvore mise ou node gravável. O cplt não consegue resolvê-lo a partir de um diretório fixo — ele legitimamente vive onde seu gerenciador de versões o colocou — então verifica o caminho resolvido contra as regras de escrita que a sandbox está prestes a aplicar e , nomeando o binário e a árvore gravável, e então prossegue

Contra o que o cplt não protege:

• Código malicioso já presente no diretório do projeto. O agente tem leitura/escrita total ali
• Bugs de lógica que o agente introduz. Você ainda revisa o código
• Um adversário sofisticado contornando a guarda de comandos. Use proteção de branch no lado do servidor
• Ataques de rede em domínios permitidos. Se github.com é permitido, o agente pode ler e escrever ali
• Acesso ao Keychain do macOS, para agentes que armazenam autenticação ali. Os conteúdos são protegidos por senha, e sandbox.keychain_substitute pode trocar a concessão onde um agente tem outra credencial

Nossas prioridades, em ordem: correto (toda afirmação é testada, todo caso extremo tem uma CVE ou referência de pesquisa), transparente (SECURITY.md não esconde nada), simples (um binário, zero configuração necessária, padrões sensatos) e útil (sair do caminho e deixar o agente trabalhar, com segurança).

Mais: docs/security.md · SECURITY.md

Rede e proxy

O proxy está ativado por padrão. Todo o tráfego de saída do Copilot CLI, gh e curl passa por um proxy CONNECT localhost via HTTP_PROXY/HTTPS_PROXY e NODE_USE_ENV_PROXY=1. Ele escuta em uma porta efêmera atribuída pelo SO, então nada colide. Você obtém registro de conexões em tempo real, bloqueio de domínios, lista de permissões de domínios, um log de auditoria persistente e a mesma política de portas que a sandbox impõe (443 mais qualquer coisa em allow.ports).```bash cplt --proxy-forced -- -p "fix tests" # force all egress through the proxy cplt --no-proxy -- -p "fix tests" # disable for one run cplt --blocked-domains blocked-domains.txt -- -p "x" # block known-bad domains cplt --allowed-domains allowed-domains.txt -- -p "x" # allowlist mode cplt --default-allowlist -- -p "x" # fail-closed: only the agent's own domains cplt --observe-domains -- -p "x" # record what the agent contacts, block nothing cplt --proxy-upstream http://proxy.corp:8080 -- -p "x" # chain through a corporate proxy

`--observe-domains-out <FILE>` grava o conjunto observado, um domínio por linha, e
`--proxy-upstream-no-proxy <HOST>` lista os hosts a serem acessados diretamente em vez de através
do upstream.```bash
cplt config set proxy.enabled false
cplt config set proxy.blocked_domains "~/.config/cplt/blocked-domains.txt"
cplt config set proxy.allowed_domains "~/.config/cplt/allowed-domains.txt"
cplt config set proxy.log_file "~/.config/cplt/proxy.log"

O modo forçado por proxy é opt-in. Ele restringe a saída do kernel à porta do proxy, de modo que um socket aberto diretamente, ou um env -u HTTPS_PROXY, não consiga escapar. A aplicação é total no macOS, que fixa em localhost:<proxy_port>. No Linux, bloqueia TCP direto para :443, e uma regra seccomp permite apenas SOCK_STREAM com protocolo 0 ou IPPROTO_TCP para AF_INET/AF_INET6, portanto UDP, raw, SCTP e DCCP também ficam fechados — ao custo de qualquer coisa que abra tal socket, não apenas código que envia UDP. O que resta é um resíduo baseado em porta, evil.com:<proxy_port>, até #114.

Fora do modo forçado por proxy, o Linux não restringe UDP. Os direitos de rede do Landlock são apenas TCP até a ABI v10, o cplt trata apenas AccessNet::ConnectTcp, e a regra seccomp acima é deliberadamente não aplicada — negar SOCK_DGRAM ali quebraria getaddrinfo(3), e portanto todo o DNS, para toda ferramenta não-proxied. UDP de saída para qualquer host, bind UDP de entrada, tunelamento DNS e QUIC/HTTP-3 ficam, portanto, sem mediação no modo padrão, e o proxy CONNECT transporta apenas TCP, então nada disso aparece no log do proxy. O macOS restringe UDP no modo padrão, mas também não o roteia: remote ip "*:443" cobre UDP, então QUIC/HTTP-3 na 443 sai sem tocar no proxy lá também. Sob proxy.forced, o log do proxy é um registro completo da saída no macOS. No Linux, é completo exceto pelo resíduo evil.com:<proxy_port> acima, que não atravessa o proxy e portanto não aparece em seu log.

Ambas as listas correspondem da mesma forma: example.com cobre o domínio exato e todos os subdomínios, a correspondência não diferencia maiúsculas de minúsculas, e pontos finais são removidos. Os arquivos de blocklist e allowlist são relidos a cada cinco segundos, então você pode editá-los ao vivo. O tráfego de localhost contorna o proxy via NO_PROXY e nunca aparece no log de auditoria. --proxy-timeout <SECONDS> limita a leitura de requisições e cabeçalhos (padrão 60) e não derruba túneis CONNECT estabelecidos, que podem ficar ociosos por até uma hora.

Cada flag de proxy, detalhe de filtragem de domínio, encadeamento de proxy corporativo upstream, e o formato do log de conexões: docs/proxy.md.

Guardas de comando

Habilite-as e o cplt intercepta gh e git através de scripts wrapper no $PATH:

Esta é a Camada 3, uma barreira suave. Ela impede que um agente complacente faça algo destrutivo por acidente. Para um limite rígido, apoie-se no sandbox do kernel e na proteção de branch do lado do servidor.

Com a guarda do gh ativada, o cplt também armazena em cache o token do GitHub na inicialização e o serve uma vez através do callback gh auth token, depois exclui o cache. Isso reduz vazamentos acidentais e baseados em ambiente. Não é um limite contra um agente hostil, porque o cache vive no próprio TMPDIR do agente e um agente que o leia antes do consumidor legítimo ainda obtém o token. SECURITY.md tem a declaração completa sobre block_auth_token.

Comportamento completo: docs/gh-guard.md · docs/git-guard.md

Impactos conhecidos

O sandbox bloqueia alguns fluxos de trabalho de propósito. Os mais comuns e suas correções:

O Playwright Chromium precisa de cplt config set sandbox.allow_cache_exec ms-playwright, e o Chromium deve rodar sem seu próprio sandbox aninhado. No macOS, seus helpers não conseguem inicializar um segundo sandbox Seatbelt dentro do cplt (forbidden-sandbox-reinit); no Linux, o filtro seccomp do cplt bloqueia as syscalls de namespace que o sandbox precisa. O Playwright como biblioteca já inicia com --no-sandbox, e esse mesmo opt-in define PLAYWRIGHT_MCP_SANDBOX=false para o Playwright MCP, que de outra forma o reativaria. Qualquer outro lançador de Chromium precisa de --no-sandbox por conta própria. O cplt continua sendo o limite de kernel aplicador, mas um renderer comprometido então recebe o perfil completo do Playwright do cplt em vez do perfil filho mais restrito do Chromium. Veja Cache exec e SECURITY.md.

O commit do Git funciona para todo agente; se o git push funciona via HTTPS depende do agente. Três pré-requisitos: use remotes HTTPS em vez de SSH (git remote set-url origin https://github.com/org/repo.git, ou reescreva globalmente com git config --global url."https://github.com/".insteadOf "[email protected]:"), execute gh auth login uma vez fora do sandbox, e execute gh auth setup-git se o credential helper ainda não estiver configurado. O push então executa gh auth git-credential, que precisa de um token que o gh consiga alcançar de dentro do sandbox — isso difere por agente, veja Git workflow. Pushes para o branch padrão e todos os force pushes são recusados pela guarda do git por padrão; faça push de um feature branch. O agent socket do SSH é bloqueado porque ele desbloqueia todas as chaves carregadas e pode autenticar em qualquer host, enquanto o credential helper do gh é restrito ao GitHub.

A JVM é proxy-aware, então um repositório Maven interno em um IP privado agora precisa ser permitido. O cplt injeta http(s).proxyHost/proxyPort em JAVA_TOOL_OPTIONS, então a resolução de dependências do Gradle e Maven passa pelo proxy CONNECT e aparece no log do proxy em vez de contorná-lo. A guarda SSRF do proxy então recusa um Nexus ou Artifactory interno que resolva para espaço de endereço privado, exatamente como já faz para curl, npm e pip. Adicione seu nome DNS a proxy.allow_private_domains. Uma URL de repositório escrita como IP literal puro (https://10.20.30.40/repository/maven-public/) não pode ser permitida por nenhuma chave — essa verificação roda antes da allow list ser consultada — então tal repositório precisa de um nome DNS. Forks de plugin WorkerExecutor, e um daemon Gradle iniciado fora do cplt e reutilizado dentro, não são proxied. Veja Internal Maven/Gradle repositories on private IPs.

O Gradle 9+ executa seu próprio sandbox aninhado, e o cplt o desativa. Desde o Gradle 8.8 o daemon se envolve em sandbox-exec (controlado por GRADLE_MACOS_SANDBOX, anteriormente a propriedade org.gradle.daemon.sandbox). O macOS não suporta chamadas sandbox-exec aninhadas, então o sandbox interno falha com "Operation not permitted" em operações de socket. O cplt injeta GRADLE_MACOS_SANDBOX=off, já que ele próprio fornece sandboxing em nível de kernel. Este é um problema upstream conhecido que afeta qualquer ferramenta que envolva o Gradle em um sandbox externo. Sobrescreva com --pass-env GRADLE_MACOS_SANDBOX se você realmente quiser o sandbox próprio do Gradle.

O Copilot CLI 1.0.83 executa seu próprio sandbox aninhado, e o cplt o desativa. No Linux, esse sandbox constrói um network namespace — slirp4netns, iptables, /dev/net/tun — e o filtro seccomp do cplt nega o unshare que ele usa. O cplt também define HTTP_PROXY/HTTPS_PROXY, o que na 1.0.83 coloca um sandbox Linux no caminho de saída do proxy, quer você tenha pedido ou não, então os dois colidem em toda inicialização. Sintoma: [cplt] Starting Copilot in sandbox... e depois nada. O cplt injeta o próprio opt-out do Copilot, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported; o Copilot se retira para a sessão, avisa isso, e deixa seu sandbox.enabled salvo intacto. O cplt é o limite, como é para Gradle e Chromium. Sobrescreva com --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. Uma política gerenciada empresarial que exija o sandbox sobrescreve tudo isso — veja Copilot CLI's own command sandbox.

Cada impacto, com as tabelas por ferramenta, notas sobre daemon JVM e Kotlin, solução de problemas de GPG, e as diferenças de plataforma de registro privado: docs/known-impacts.md.

Limitações

macOS

• sandbox-exec está obsoleto. A Apple não o removeu, mas pode removê-lo em uma versão futura do macOS.
• SBPL não tem filtragem baseada em domínio. O proxy CONNECT opcional fornece bloqueio de domínio em vez disso.
• O lsopen do SBPL também não tem filtro, então --allow-browser é todo o Launch Services ou nada dele. Com ele ativado, o agente pode lançar qualquer aplicação fora do sandbox, e nenhum wrapper pode restringir isso — veja docs/security.md.

Linux

• Kernel 5.13+ necessário, com Landlock LSM habilitado.
• A filtragem de porta TCP precisa do kernel 6.7+. Kernels mais antigos recebem apenas aplicação de filesystem.
• O Landlock não pode negar subcaminhos dentro de caminhos permitidos, então leitura/escrita/exclusão de .env dentro do diretório do projeto não é aplicada pelo kernel. Escritas em .git/hooks são bloqueadas quando o Bubblewrap está ativo.
• --deny-path requer Bubblewrap. É aplicado através de máscaras de mount quando o bwrap está ativo. Sem ele, o Landlock é apenas allowlist e o cplt avisa sobre o deny em vez de aplicá-lo.

Mais: docs/security.md

Contribuindo

Contribuições são bem-vindas.```bash git clone https://github.com/navikt/cplt.git && cd cplt git config core.hooksPath hack # enables pre-commit fmt + clippy checks mise run check # runs fmt, clippy, and tests

Abra uma issue antes de iniciar uma grande alteração. Todo PR precisa passar pelo CI (fmt, clippy, testes).

## Referências

- [SECURITY.md](https://github.com/navikt/cplt/blob/main/SECURITY.md), o modelo de segurança completo, análise de ameaças, estratégia de testes e trabalhos anteriores
- [Apple sandbox-exec(1)](https://keith.github.io/xcode-man-pages/sandbox-exec.1.html)
- [Chromium Seatbelt V2 Design](https://chromium.googlesource.com/chromium/src/sandbox/+show/refs/heads/main/mac/seatbelt_sandbox_design.md)
- [Documentação do Landlock LSM](https://docs.kernel.org/userspace-api/landlock.html)
- [Documentação do seccomp-BPF](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)
- [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
- [michaelneale/agent-seatbelt-sandbox](https://github.com/michaelneale/agent-seatbelt-sandbox)

## Licença

[MIT](https://github.com/navikt/cplt/blob/main/LICENSE)