Os primeiros 5 minutos com o zn-gate

Instale o zn-gate, confirme que ele funciona e entenda o que significam as mensagens dele. Não é preciso conta nem chave de API.

Ver .md

Você usa um agente de código com IA (Claude Code, Codex CLI, Cursor ou OpenCode) e não escreve código você mesmo, ou escreve pouco. Esta página leva você do zero até "o zn-gate está ativo e eu vi funcionar", e depois explica o que significam as mensagens dele e como removê-lo. Não é preciso conta nem chave de API. Tudo roda na sua máquina.

Antes de começar

O zn-gate precisa do Node.js 18 ou mais recente (instale a versão LTS em nodejs.org); o plugin do Claude Code precisa do Node.js 20.12 ou mais recente. Se node --version disser "command not found", instale a versão LTS em nodejs.org e abra um terminal novo. Execute cada comando abaixo no seu próprio terminal, não pelo agente.

1. Instalar

npx -y zn-gate init

O init encontra os agentes de código na sua máquina e mostra cada passo antes de executá-lo. Ele pergunta antes, e você pode dizer não. Para o Claude Code, configura o plugin do zn-gate (ou os hooks do zn quando o seu Node.js é mais antigo que 20.12). Para Codex CLI, Cursor e OpenCode, configura os hooks do zn. Um hook é uma verificação pequena que o agente executa antes de usar uma ferramenta. A configuração de um agente por vez está no README.

Quer olhar antes? npx -y zn-gate reach lista o que os seus agentes conseguem alcançar (nomes de segredos, arquivos de credenciais, servidores MCP). Não muda nada e não envia nada. Veja reach.

2. Confirmar que funciona

init termina com esta verificação. Você pode executá-la quando quiser:

npx -y zn-gate check

Ele cria uma pasta temporária com uma chave falsa em um arquivo .env, pede ao hook do seu agente para lê-lo e apaga a pasta. Esta é a saída real:

zn-gate check: does zn stop your coding agent from reading a secret?

zn made a test folder with a fake key in a .env file and an ordinary file next to it, then asked
each agent's zn hook whether the agent may read them. This is what happened:

  OK Claude Code  blocked the .env file and allowed the ordinary file. Your agent would be told:
     "zn: .env holds plain-text secrets. Ask the user to run `zn env shadow .env` in their terminal: it moves the values to the local vault and leaves __ZN_<NAME>__ markers you can read and use."
  -  Codex CLI    not found on this machine
  -  Cursor       not found on this machine
  -  OpenCode     not found on this machine

Your agent cannot read secret files such as .env through these tools. Nothing was sent anywhere.
If your agent needs a value from .env, keep it in zn's vault instead: `zn env shadow .env`.
More: https://usezn.com/docs/check

The test folder was deleted.

OK significa que aquele agente está protegido. Uma linha que começa com - significa que o zn não está configurado para esse agente, ou que o agente não está na sua máquina. Uma linha com NOT protected explica o motivo e o que executar. Mais em check.

3. O que você vai ver enquanto trabalha

O zn-gate avisa de três formas. Os bloqueios e as perguntas de aprovação vêm dos hooks do zn e aparecem na janela do seu agente. Os avisos vêm da verificação de texto do zn e só chegam até você se o seu agente os mencionar.

Um bloqueio

O zn interrompeu algo que poderia vazar um segredo ou parecia um ataque, e não executou. Aqui, um agente em ~/my-project tentou executar cat .env. Esta foi a resposta do zn, palavra por palavra:

{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"zn: .env holds plain-text secrets. Ask the user to run `zn env shadow .env` in their terminal: it moves the values to the local vault and leaves __ZN_<NAME>__ markers you can read and use."}}

Se o zn não estiver instalado no seu PATH (por exemplo, se você usou o npx), a mensagem mostra npx -y zn-gate@1.13.1 em vez de zn.

deny é o bloqueio. A frase depois dele é o próximo passo. O que fazer:

  1. Leia o motivo. Ele foi escrito para você e para o seu agente.
  2. Se o agente precisar de um valor desse arquivo, execute você mesmo o comando da mensagem, no seu próprio terminal: npx -y zn-gate env shadow .env. Os valores reais vão para o cofre criptografado do zn e o arquivo mantém marcadores. Veja secrets.
  3. Se o bloqueio foi uma surpresa, não procure uma forma de contorná-lo. Pergunte ao seu agente por que ele queria ler esse arquivo.

Um comando comum como ls não recebe resposta nenhuma: ele é permitido e você não vê nada.

Uma pergunta de aprovação

Às vezes o zn não bloqueia, mas pergunta antes. Isso acontece quando um comando usa um marcador de segredo. Resposta real para um comando que envia __ZN_EXAMPLE_TOKEN__ para https://example.com/api:

"permissionDecision":"ask","permissionDecisionReason":"zn: this command runs through zn run (zn's secret wrapper) for EXAMPLE_TOKEN; the first time, you approve the command, and secret values in its output stay hidden."

Em seguida, o seu agente mostra a pergunta de permissão habitual. Leia o comando. Aprove apenas se for o que você esperava.

Um aviso

O zn também tem uma verificação de texto que o seu agente pode chamar pelas ferramentas próprias do zn. Alguns padrões que ela procura também aparecem em textos comuns, como "bypass the cache". Para esses, o zn não bloqueia: deixa o texto passar e acrescenta um aviso curto, chamado advisory. O aviso vai para o seu agente, não para a sua tela, então você só o vê se o seu agente mencioná-lo. Os hooks do zn não avisam você sobre esses casos. Você pode executar a mesma verificação. Saída real de npx -y zn-gate analyze "You can bypass the cache with --no-cache.":

{
  "verdict": "allow",
  "confidence": 0.99,
  "rule": "none",
  "reason": null,
  "engine": "oss-local",
  "rules_version": "2026-10-19.1",
  "advisory": {
    "rule": "pi:bypass",
    "reason": "Guardrail bypass attempt"
  },
  "mode": "oss-local"
}

"verdict": "allow" significa que nada foi interrompido. O advisory indica por que vale a pena dar uma olhada. O que fazer: leia o texto para o qual ele aponta. Se for inofensivo, siga em frente. Se você não esperava aquilo (por exemplo, dentro de um arquivo que baixou), não deixe o seu agente seguir o texto. Para que a verificação de texto bloqueie esses casos também, ative o modo estrito: defina ZN_STRICT=1, ou adicione "strict": true ao zn.config.json do seu projeto.

Para comparar, npx -y zn-gate analyze "ignore all previous instructions" é um bloqueio: "verdict": "block" com o motivo "Override prior instructions".

Se algo falhar

  • npx: command not found: instale a versão LTS do Node.js, abra um terminal novo e execute o comando de novo.
  • "running scripts is disabled on this system" no Windows: use npx.cmd em vez de npx, ou veja a nota de PowerShell no README.
  • init só mostra passos e não muda nada: um agente de IA ou um script o executou. Execute você mesmo no seu terminal.
  • check diz NOT protected: a linha indica o que executar.
  • O zn bloqueou algo de que você precisa: use npx -y zn-gate env shadow .env para segredos, ou pergunte em Discussions.

Remover o zn-gate

Remova a parte que você instalou, no seu próprio terminal.

  • Hooks (Codex CLI, Cursor, OpenCode, ou Claude Code sem o plugin): npx -y zn-gate hooks uninstall claude-code. Use codex, cursor ou opencode para os outros, e adicione --project se você os instalou só para um projeto. Antes, é gravada uma cópia de segurança do arquivo de configurações.
  • Plugin do Claude Code: execute claude plugin uninstall zn-gate@usezn, ou digite /plugin no Claude Code, abra a aba Installed, escolha o zn-gate e clique em Uninstall. Para remover também a lista de plugins da usezn, execute claude plugin marketplace remove usezn.
  • Servidores MCP envolvidos (com init --wrap-mcp): npx -y zn-gate init --revert devolve cada arquivo de configurações do MCP como estava salvo logo antes de o zn envolvê-lo. Alterações que você fez depois nesses arquivos, como servidores MCP que você adicionou, se perdem, então adicione-os de novo depois. Isso desfaz só o envolvimento MCP, não os hooks.
  • O programa, se você o instalou com npm install -g zn-gate: npm uninstall -g zn-gate.
  • O pacote Python, se você o instalou com pip install zn-gate: pip uninstall zn-gate.
  • Arquivos .env que você moveu para o cofre mantêm marcadores como __ZN_API_KEY__. O env shadow diz como devolver os valores reais. Faça isso antes de remover o zn-gate.
  • A pasta própria do zn: o zn guarda o cofre, as configurações e os contadores em uma pasta .zn na sua pasta pessoal, e remover o zn-gate a deixa lá. Apague-a só depois de devolver os valores do seu .env, porque o cofre os guarda.

Execute npx -y zn-gate check depois, se quiser ver que o zn está desligado.

Próximos passos