zn-gate (local)

Configuration

Environment variables, command-line flags and custom rules for zn-gate.

View .md

zn-gate works with no configuration. Everything below is optional.

Environment variables

Variable Default Effect
ZN_CLOUD off 1 lets prompt analysis (analyze_prompt, zn-gate analyze, Python analyze()) also ask the cloud model for a second opinion. Requires ZN_API_KEY.
ZN_API_KEY unset API key from the dashboard. No effect without ZN_CLOUD=1.
ZN_LOCAL_ONLY unset true forces local-only, even with ZN_CLOUD=1.
ZN_STAGE v30 Cloud endpoint: v30 (current production API) or prod (legacy endpoint).
ZN_API_URL unset Overrides the cloud endpoint URL. Takes precedence over ZN_STAGE.
ZN_VERBOSE unset Any value turns on debug logging to stderr.

npx -y zn-gate status prints the active engine and what your configuration sends. See What leaves your machine.

Turn on the cloud for one MCP server

Add the variables to that server's entry in your agent config, for example in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "zn-gate": {
      "command": "npx",
      "args": ["-y", "zn-gate", "mcp"],
      "env": { "ZN_CLOUD": "1", "ZN_API_KEY": "zn_live_your_key" }
    }
  }
}

Command-line flags

Flag Effect
--local-only Never use the cloud, even if ZN_CLOUD=1 is set
--key <api_key> API key for the optional cloud (same as ZN_API_KEY; still needs ZN_CLOUD=1)
--stage v30 or --stage prod, --url <url> Cloud endpoint selection
--shadow With init or shield: log detections without blocking or altering traffic
--all, --include .rst,.xml, --exclude fixtures Control which files scan reads
--verbose Debug logging to stderr

Run npx -y zn-gate --help for every option.

Custom rules

In the Node.js package, add banned patterns and forbidden paths for your project in .znrules or zn.config.json in the directory zn-gate runs from:

# .znrules
path:.env.production
path:/etc/secrets
CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+

Lines starting with path: block any input that contains that path. Other lines are case-insensitive regular expressions that block any input they match. Lines starting with # are comments. The JSON form:

{ "bannedPatterns": ["CONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+"], "forbiddenPaths": [".env.production", "/etc/secrets"] }

Blocks from custom rules report custom:banned_pattern or custom:forbidden_path. The Python package does not read these files.

Files zn-gate writes

File What it is
~/.zn/evidence.jsonl Local audit log of shield decisions (details)
<config>.bak.<timestamp> Backup of each agent config that init changes; init --revert restores the latest