Primeros 5 minutos con zn-gate

Instala zn-gate, comprueba que funciona y entiende qué significan sus mensajes. No necesitas cuenta ni clave de API.

Ver .md

Usas un agente de código con IA (Claude Code, Codex CLI, Cursor u OpenCode) y no escribes código tú mismo, o escribes poco. Esta página te lleva de cero a "zn-gate está activo y lo he visto funcionar", y después te explica qué significan sus mensajes y cómo quitarlo. No necesitas cuenta ni clave de API. Todo se ejecuta en tu máquina.

Antes de empezar

zn-gate necesita Node.js 18 o posterior (instala la versión LTS desde nodejs.org); el plugin de Claude Code necesita Node.js 20.12 o posterior. Si node --version responde "command not found", instala la versión LTS desde nodejs.org y abre una terminal nueva. Ejecuta cada comando de abajo en tu propia terminal, no a través de tu agente.

1. Instalar

npx -y zn-gate init

init busca los agentes de código de tu máquina y muestra cada paso antes de ejecutarlo. Te pregunta primero, y puedes decir que no. Para Claude Code instala el plugin de zn-gate (o los hooks de zn cuando tu Node.js es anterior a la 20.12). Para Codex CLI, Cursor y OpenCode instala los hooks de zn. Un hook es una comprobación pequeña que tu agente ejecuta antes de usar una herramienta. La configuración de un agente cada vez está en el README.

¿Quieres mirar antes? npx -y zn-gate reach lista lo que tus agentes pueden alcanzar (nombres de secretos, archivos de credenciales, servidores MCP). No cambia nada y no envía nada. Consulta reach.

2. Comprobar que funciona

init termina con esta comprobación. Puedes ejecutarla cuando quieras:

npx -y zn-gate check

Crea una carpeta temporal con una clave falsa en un archivo .env, pide al hook de tu agente que lo lea y borra la carpeta. Esta es la salida real:

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 significa que ese agente está protegido. Una línea que empieza por - significa que zn no está configurado para ese agente, o que el agente no está en tu máquina. Una línea con NOT protected explica el motivo y qué ejecutar. Más en check.

3. Lo que verás mientras trabajas

zn-gate avisa de tres formas. Los bloqueos y las preguntas de aprobación vienen de los hooks de zn y aparecen en la ventana de tu agente. Las advertencias vienen de la comprobación de texto de zn y solo llegan a ti si tu agente te las cuenta.

Un bloqueo

zn detuvo algo que podía filtrar un secreto o parecía un ataque, y no se ejecutó. Aquí, un agente en ~/my-project intentó ejecutar cat .env. Esto es lo que respondió zn, palabra por palabra:

{"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 no está instalado en tu PATH (por ejemplo, si usaste npx), el mensaje muestra npx -y zn-gate@1.13.1 en lugar de zn.

deny es el bloqueo. La frase que viene después es el siguiente paso. Qué hacer:

  1. Lee el motivo. Está escrito para ti y para tu agente.
  2. Si el agente necesita un valor de ese archivo, ejecuta tú el comando del mensaje, en tu propia terminal: npx -y zn-gate env shadow .env. Los valores reales pasan a la bóveda cifrada de zn y el archivo conserva marcadores. Consulta secrets.
  3. Si el bloqueo te sorprendió, no busques la forma de saltártelo. Pregunta a tu agente por qué quería leer ese archivo.

Un comando normal como ls no recibe ninguna respuesta: se permite y no ves nada.

Una pregunta de aprobación

A veces zn no bloquea, sino que pregunta primero. Pasa cuando un comando usa un marcador de secreto. Respuesta real para un comando que envía __ZN_EXAMPLE_TOKEN__ a 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."

Después tu agente muestra su pregunta de permisos habitual. Lee el comando. Apruébalo solo si es lo que esperabas.

Una advertencia

zn también tiene una comprobación de texto que tu agente puede llamar mediante las herramientas propias de zn. Algunos patrones que busca aparecen también en texto corriente, como "bypass the cache". Para esos, zn no bloquea: deja pasar el texto y añade una advertencia breve, llamada advisory. La advertencia va a tu agente, no a tu pantalla, así que solo la ves si tu agente la menciona. Los hooks de zn no te avisan de estos casos. Puedes ejecutar la misma comprobación tú mismo. Salida real 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" significa que no se detuvo nada. El advisory indica por qué merece una mirada. Qué hacer: lee el texto al que apunta. Si es inofensivo, sigue adelante. Si no lo esperabas (por ejemplo, dentro de un archivo que descargaste), no dejes que tu agente lo siga. Para que la comprobación de texto bloquee también estos casos, activa el modo estricto: pon ZN_STRICT=1, o añade "strict": true a zn.config.json en tu proyecto.

Para comparar, npx -y zn-gate analyze "ignore all previous instructions" sí es un bloqueo: "verdict": "block" con el motivo "Override prior instructions".

Si algo falla

  • npx: command not found: instala la versión LTS de Node.js, abre una terminal nueva y vuelve a ejecutar el comando.
  • "running scripts is disabled on this system" en Windows: usa npx.cmd en lugar de npx, o consulta la nota de PowerShell en el README.
  • init solo muestra pasos y no cambia nada: un agente de IA o un script lo ejecutó. Ejecútalo tú en tu propia terminal.
  • check dice NOT protected: la línea indica qué ejecutar.
  • zn bloqueó algo que necesitas: usa npx -y zn-gate env shadow .env para los secretos, o pregunta en Discussions.

Quitar zn-gate

Quita la parte que instalaste, en tu propia terminal.

  • Hooks (Codex CLI, Cursor, OpenCode, o Claude Code sin el plugin): npx -y zn-gate hooks uninstall claude-code. Usa codex, cursor u opencode para los demás, y añade --project si los instalaste solo para un proyecto. Antes se escribe una copia de seguridad del archivo de ajustes.
  • Plugin de Claude Code: ejecuta claude plugin uninstall zn-gate@usezn, o escribe /plugin en Claude Code, abre la pestaña Installed, elige zn-gate y pulsa Uninstall. Para quitar también la lista de plugins de usezn, ejecuta claude plugin marketplace remove usezn.
  • Servidores MCP envueltos (con init --wrap-mcp): npx -y zn-gate init --revert devuelve cada archivo de ajustes de MCP tal como estaba guardado justo antes de que zn lo envolviera. Los cambios que hiciste después en esos archivos, como los servidores MCP que añadiste, se pierden, así que añádelos de nuevo después. Solo deshace el envoltorio MCP, no los hooks.
  • El programa, si lo instalaste con npm install -g zn-gate: npm uninstall -g zn-gate.
  • El paquete de Python, si lo instalaste con pip install zn-gate: pip uninstall zn-gate.
  • Archivos .env que moviste a la bóveda: conservan marcadores como __ZN_API_KEY__. env shadow te indica cómo devolver los valores reales. Hazlo antes de quitar zn-gate.
  • La carpeta propia de zn: zn guarda su bóveda, sus ajustes y sus contadores en una carpeta .zn en tu carpeta personal, y quitar zn-gate la deja ahí. Bórrala solo después de devolver los valores de tu .env, porque la bóveda los guarda.

Ejecuta npx -y zn-gate check después si quieres ver que zn está desactivado.

Dónde seguir