zn-gate for Codex CLI

Install zn's hooks for Codex CLI: they block reads of .env files with values and credential files, scrub tool output and block secrets pasted into prompts.

View .md

You need Node.js 18 or later. Paste each line in a terminal and press Enter after each one:

npm install -g zn-gate
zn hooks install codex

Then open Codex and approve the new hooks with /hooks.

What you get

  • Reads of .env files with values, credential files and ~/.zn are blocked, in shell commands and in patches (apply_patch).
  • Tool output is scrubbed before the model sees it. Codex replaces the result with its scrubbed text, so the model gets text instead of the structured result.
  • A secret pasted into a prompt is blocked.
  • For a command that uses a __ZN_<NAME>__ marker, Codex is told the exact zn run -- ... line to use.

Limits

  • Codex calls its hooks "a guardrail, not an enforcement boundary". If the zn hook cannot run, Codex reports it as failed and the call or prompt goes ahead.
  • Codex's own session log keeps the original output.
  • On Windows, the hook command was run by hand from PowerShell and from Command Prompt, not in our automated tests.

Keep your .env values in the vault

The agent cannot read .env files with real values. Move the values into zn-gate's encrypted vault, and the file keeps markers such as __ZN_STRIPE_KEY__:

zn unlock            # creates the vault the first time
zn env shadow .env

After this your own app also reads the markers: start it with zn-gate's run command once you allow it. env shadow tells you how to undo it. More: the vault.

Check that it works

In a new terminal, run zn-gate check. It should show OK for Codex CLI. What the output means.

On Windows PowerShell, if npm says "running scripts is disabled on this system", use npm.cmd and zn.cmd instead: see Install.