# Architecture

How zn-gate is built. Three checkpoints around every agent action, and the principles behind them.

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

zn-gate is a small checkpoint that runs on your machine, between your coding agent and everything it reads and runs. It looks at three moments of every action and stays out of the way the rest of the time. This page explains the layout and the principles behind it. For the pieces in detail, see [How zn-gate works](https://usezn.com/docs/concepts/).

## Three checkpoints

<figure class="zn-diagram">
<img src="/diagrams/v2/en/defense-in-depth.svg" width="800" height="437" loading="lazy" decoding="async" alt="Diagram of three checkpoints inside zn-gate on your machine. Step 1: a prompt or content goes through analyze_prompt, which checks it for injection and pasted secrets, before it reaches the agent. Step 2: the agent's tool call goes through check_tool_call, which blocks risky arguments and masks secrets, before the tool runs. Step 3: the tool output goes through check_tool_result, which redacts secrets and neutralizes injections, before it reaches the model.">
<button type="button" class="zn-diagram-replay" data-src="/diagrams/v2/en/defense-in-depth.svg" aria-label="Replay" onclick="var i=this.parentNode.querySelector(&#x27;img&#x27;),u=new URL(this.dataset.src,location.href);u.searchParams.set(&#x27;replay&#x27;,Date.now());i.src=u.href">Replay</button>
</figure>

| Step | Checkpoint | When | What it does |
| - | - | - | - |
| 1 | `analyze_prompt` | Before the agent acts on a prompt or on content | Looks for prompt injection, jailbreaks and secrets pasted into the text |
| 2 | `check_tool_call` | Before a tool runs | Checks the arguments for injection, exfiltration patterns and sensitive paths. A blocked call never reaches the tool. Secrets in the arguments are masked |
| 3 | `check_tool_result` | After the tool runs, before the model reads the output | Redacts secrets and neutralizes indirect prompt injection. A result that carries an injection is replaced by a short notice |

Each checkpoint answers `allow` or `block` and names the `rule` and the `reason` that decided it. The same three checks work in each of the ways zn-gate can be set up: agent hooks, the MCP server, or `zn-gate shield` in front of your other MCP servers. The setups and what each one covers are in [How zn-gate works](https://usezn.com/docs/concepts/).

## Principles

1. **Few dependencies.** The Python package uses only the standard library. The npm package has one runtime dependency, `age-encryption` (with its `@noble` and `@scure` libraries), which encrypts the secret vault. It is bundled in the package at the versions pinned in `package-lock.json`, and nothing is compiled on your machine.
2. **Local and predictable first.** The checks run on your machine with fixed rules: pattern matching plus normalization of look-alike characters, zero-width characters and encoded text. The same input gives the same answer, and every answer names its rule. The last 2,048 results are cached, so repeated text is checked once. Measured times are on the [Performance](https://usezn.com/docs/zn-gate/performance/) page.
3. **An optional second opinion from the cloud.** Only prompt analysis can ask the cloud classifier, and only after you turn it on: set both `ZN_API_KEY` and `ZN_CLOUD=1`, or run `zn-gate connect`. `ZN_LOCAL_ONLY=true` turns it off again. Text the local rules already block is never sent, and secrets in the text are removed on your machine before anything is sent (personal data is not). Tool arguments, tool output and tool descriptions never leave your machine, in any setting. Details: [What leaves your machine](https://usezn.com/docs/what-leaves-your-machine/).
4. **A tamper-evident local log.** Each decision recorded by `zn-gate shield` and the SDKs is added to `~/.zn/evidence.jsonl` with a SHA-256 hash that links it to the previous one, with a redacted preview and never the secret itself. `zn-gate evidence --verify` checks the chain. It detects accidental or partial edits, but it is not proof against someone who can write to the file, because they can recompute it. See [Evidence](https://usezn.com/docs/zn-gate/evidence/).

## What this layout does not do

- It is one boundary, not your whole security model. Keep least-privilege tool scopes and human review for high-impact actions.
- What the checkpoints can see depends on how zn-gate is set up and on the agent. An MCP server alone only sees the calls your agent chooses to send it. The hooks also cover the agent's built-in tools, to the extent each agent allows. See [Threat model](https://usezn.com/docs/threat-model/).
- The local rules are not a semantic classifier: paraphrased attacks can get through.