# Configuration

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

Source: https://usezn.com/docs/zn-gate/configuration/

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](https://usezn.com/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](https://usezn.com/docs/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`:

```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:

```ini
# .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:

```json
{ "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](https://usezn.com/docs/zn-gate/evidence/)) |
| `<config>.bak.<timestamp>` | Backup of each agent config that `init` changes; `init --revert` restores the latest |