Les 5 premières minutes avec zn-gate

Installez zn-gate, vérifiez qu'il fonctionne et comprenez ce que signifient ses messages. Aucun compte ni clé d'API n'est nécessaire.

Voir le .md

Vous utilisez un agent de code IA (Claude Code, Codex CLI, Cursor ou OpenCode) et vous n'écrivez pas de code vous-même, ou très peu. Cette page vous mène de zéro à « zn-gate est actif et je l'ai vu fonctionner », puis explique ce que signifient ses messages et comment le retirer. Aucun compte ni clé d'API n'est nécessaire. Tout s'exécute sur votre machine.

Avant de commencer

zn-gate nécessite Node.js 18 ou une version ultérieure (installez la version LTS depuis nodejs.org) ; le plugin Claude Code nécessite Node.js 20.12 ou une version ultérieure. Si node --version répond « command not found », installez la version LTS depuis nodejs.org et ouvrez un nouveau terminal. Exécutez chaque commande ci-dessous dans votre propre terminal, et non via votre agent.

1. Installer

npx -y zn-gate init

init repère les agents de code sur votre machine et affiche chaque étape avant de l'exécuter. Il vous demande d'abord, et vous pouvez refuser. Pour Claude Code, il installe le plugin zn-gate (ou les hooks de zn si votre Node.js est antérieur à la 20.12). Pour Codex CLI, Cursor et OpenCode, il installe les hooks de zn. Un hook est une petite vérification que votre agent exécute avant d'utiliser un outil. La configuration pour un agent à la fois est décrite dans le README.

Vous voulez regarder avant ? npx -y zn-gate reach liste ce que vos agents peuvent atteindre (noms de secrets, fichiers d'identifiants, serveurs MCP). Il ne modifie rien et n'envoie rien. Voir reach.

2. Vérifier que ça fonctionne

init se termine par cette vérification. Vous pouvez la lancer à tout moment :

npx -y zn-gate check

Elle crée un dossier temporaire avec une fausse clé dans un fichier .env, demande au hook de votre agent de le lire, puis supprime le dossier. Voici la sortie réelle :

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 signifie que cet agent est protégé. Une ligne qui commence par - signifie que zn n'est pas configuré pour cet agent, ou que l'agent n'est pas installé sur votre machine. Une ligne NOT protected explique pourquoi et ce qu'il faut lancer. Plus de détails dans check.

3. Ce que vous verrez pendant votre travail

zn-gate se manifeste de trois façons. Les blocages et les demandes d'approbation viennent des hooks de zn et apparaissent dans la fenêtre de votre agent. Les avertissements viennent de la vérification de texte de zn et ne vous parviennent que si votre agent vous les signale.

Un blocage

zn a arrêté une action qui pouvait divulguer un secret ou ressemblait à une attaque, et elle n'a pas été exécutée. Ici, un agent dans ~/my-project a tenté d'exécuter cat .env. Voici la réponse de zn, mot pour mot :

{"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."}}

Si zn n'est pas installé dans votre PATH (par exemple si vous avez utilisé npx), le message affiche npx -y zn-gate@1.13.1 à la place de zn.

deny est le blocage. La phrase qui suit indique l'étape suivante. Que faire :

  1. Lisez le motif. Il est écrit pour vous et pour votre agent.
  2. Si l'agent a besoin d'une valeur de ce fichier, lancez vous-même la commande du message, dans votre propre terminal : npx -y zn-gate env shadow .env. Les vraies valeurs passent dans le coffre chiffré de zn et le fichier conserve des marqueurs. Voir secrets.
  3. Si le blocage vous surprend, ne cherchez pas à le contourner. Demandez à votre agent pourquoi il voulait lire ce fichier.

Une commande ordinaire comme ls ne reçoit aucune réponse : elle est autorisée et vous ne voyez rien.

Une question d'approbation

Parfois, zn ne bloque pas mais demande d'abord. Cela arrive quand une commande utilise un marqueur de secret. Réponse réelle pour une commande qui envoie __ZN_EXAMPLE_TOKEN__ à 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."

Votre agent affiche alors sa question de permission habituelle. Lisez la commande. Ne l'approuvez que si c'est bien ce que vous attendiez.

Un avertissement

zn dispose aussi d'une vérification de texte que votre agent peut appeler via les outils propres à zn. Certains motifs qu'elle recherche apparaissent aussi dans un texte ordinaire, comme « bypass the cache ». Pour ceux-là, zn ne bloque pas : il laisse passer le texte et ajoute un court avertissement, appelé advisory. L'avertissement va à votre agent, et non à votre écran : vous ne le voyez que si votre agent en parle. Les hooks de zn ne vous avertissent pas de ces cas. Vous pouvez lancer vous-même la même vérification. Sortie réelle 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" signifie que rien n'a été arrêté. Le advisory indique pourquoi le passage mérite un coup d'œil. Que faire : lisez le texte désigné. S'il est inoffensif, continuez. Si vous ne l'attendiez pas (par exemple dans un fichier que vous avez téléchargé), ne laissez pas votre agent le suivre. Pour que la vérification de texte bloque aussi ces cas, activez le mode strict : définissez ZN_STRICT=1, ou ajoutez "strict": true à zn.config.json dans votre projet.

Pour comparer, npx -y zn-gate analyze "ignore all previous instructions" est un blocage : "verdict": "block" avec le motif « Override prior instructions ».

Si quelque chose échoue

  • npx: command not found : installez la version LTS de Node.js, ouvrez un nouveau terminal et relancez la commande.
  • « running scripts is disabled on this system » sous Windows : utilisez npx.cmd au lieu de npx, ou consultez la note PowerShell du README.
  • init n'affiche que des étapes et ne change rien : un agent IA ou un script l'a lancé. Lancez-le vous-même dans votre propre terminal.
  • check affiche NOT protected : la ligne indique quoi lancer.
  • zn a bloqué quelque chose dont vous avez besoin : utilisez npx -y zn-gate env shadow .env pour les secrets, ou posez la question dans Discussions.

Retirer zn-gate

Retirez la partie que vous avez installée, dans votre propre terminal.

  • Hooks (Codex CLI, Cursor, OpenCode, ou Claude Code sans le plugin) : npx -y zn-gate hooks uninstall claude-code. Utilisez codex, cursor ou opencode pour les autres, et ajoutez --project si vous les avez installés pour un seul projet. Une copie de sauvegarde du fichier de réglages est écrite avant.
  • Plugin Claude Code : lancez claude plugin uninstall zn-gate@usezn, ou tapez /plugin dans Claude Code, ouvrez l'onglet Installed, choisissez zn-gate et cliquez sur Uninstall. Pour retirer aussi la liste de plugins usezn, lancez claude plugin marketplace remove usezn.
  • Serveurs MCP encapsulés (avec init --wrap-mcp) : npx -y zn-gate init --revert remet chaque fichier de réglages MCP tel qu'il était enregistré juste avant que zn ne l'encapsule. Les modifications que vous y avez faites ensuite, comme les serveurs MCP ajoutés, sont perdues : ajoutez-les de nouveau après. Cela ne défait que l'encapsulation MCP, pas les hooks.
  • Le programme lui-même, si vous l'avez installé avec npm install -g zn-gate : npm uninstall -g zn-gate.
  • Le paquet Python, si vous l'avez installé avec pip install zn-gate : pip uninstall zn-gate.
  • Les fichiers .env que vous avez déplacés dans le coffre gardent des marqueurs comme __ZN_API_KEY__. env shadow vous indique comment remettre les vraies valeurs. Faites-le avant de retirer zn-gate.
  • Le dossier propre à zn : zn garde son coffre, ses réglages et ses compteurs dans un dossier .zn de votre dossier personnel, et retirer zn-gate le laisse en place. Supprimez-le seulement après avoir remis les valeurs de votre .env, car le coffre les contient.

Lancez npx -y zn-gate check ensuite si vous voulez vérifier que zn est désactivé.

Pour aller plus loin