Solución de problemas

Inyección high/prod rechazada — “not on the executor allowlist”

Un valor high o prod solo puede inyectarse en un ejecutable revisado y en la allowlist. Agregarlo para la corrida con --allow:

kovra run --env prod --allow ./deploy -- ./deploy

Esto es distinto del prompt de bioProve — gobierna adónde puede ir el valor, no si se preguntó. Ver el proceso de decisión.

Una ejecución que entrega un valor high o prod recibe además un entorno saneado: el PATH queda fijo en /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin, y se quitan las variables que hacen que un shell, un intérprete o el cargador dinámico ejecuten código adicional (BASH_ENV, ZDOTDIR, NODE_OPTIONS, PYTHONPATH, DYLD_*, LD_*, GIT_SSH_COMMAND, EDITOR, PAGER, …). Si el programa depende de alguna, defínala dentro del propio programa.

kovra allow add rechazado — “runs whatever script it is given”

Los intérpretes y lanzadores genéricos — sh, bash, zsh, env, python, node, ruby, perl, osascript, make, npm, npx, cargo, docker, … — no se pueden agregar a la allowlist: agregar uno permitiría que cualquier script que escriba un agente reciba valores críticos. Agregue en su lugar el script revisado (con su línea shebang).

kovra allow list muestra “changed since it was approved”

Cada entrada de la allowlist fija el contenido del programa que usted revisó. Si el archivo se editó desde entonces, ya no está en la allowlist. Revise el cambio y ejecute kovra allow add otra vez.

“the master key in the keyring does not open this vault”

La clave del Keychain no es la de esta bóveda: fue sustituida (cualquier programa que corre con su usuario puede reescribir ese ítem del Keychain sin ningún prompt) o pertenece a otra bóveda. kovra no lee ni sella con ella. El mensaje nombra lo que no abre: keycheck.sec cuando la clave no es la de la bóveda, o los registros (global/<id>.sec, projects/<nombre>/<id>.sec) y la lista de sombras (shadows.sec) que no abren — archivos puestos desde otra bóveda (hasta cinco, y cuántos más). Si la clave es la correcta, saque de la bóveda los archivos nombrados. Si no, restaure la clave correcta desde su respaldo con kovra key import. key import a su vez restaura solo una clave que abre los registros de la bóveda — “this backup’s key does not open the vault” significa que el respaldo pertenece a otra bóveda.

kovra init rechazado — “holds sealed records but its key is missing”

La bóveda ya guarda registros sellados y el keyring no tiene clave para ellos. Restaure la clave con kovra key import. kovra init --force (con su aprobación) crea una clave nueva y deja esos registros ilegibles. Si kovra no pudo leer la clave (un Touch ID cancelado, un keychain bloqueado), init se detiene en lugar de crear una: ejecútelo otra vez.

Edición rechazada — “two separate edits”

En un secreto crítico (high o inject-only), una sola edición no puede cambiar a la vez su sensibilidad y su referencia. Haga dos ediciones, cada una con su propia aprobación.

kovra ssh-add rechazado

ssh-add entrega la clave privada misma a lo que responda en $SSH_AUTH_SOCK, así que rechaza las claves high, inject-only y de prod. Úselas a través de kovra ssh-agent, que firma cada solicitud sin entregar la clave.

El prompt de bioProve nunca aparece

En una Mac, kovra pide Touch ID, o la contraseña de su sesión si la Mac no tiene Touch ID (o no está configurado). Por SSH, o donde no haya sesión gráfica, no se puede mostrar el diálogo: con un teléfono vinculado, la solicitud va a la app de aprobación de kovra en ese teléfono (kovra Mobile, próximamente); sin teléfono vinculado, lo que necesita su aprobación se rechaza: ejecútelo desde el escritorio de la Mac. La llave maestra y la vinculación se aprueban solo en la Mac. kovra nunca recae en una aprobación que un agente pueda darse a sí mismo. (KOVRA_CONFIRMER y kovra approve aplican a builds de desarrollo y a plataformas distintas de macOS.)

macOS vuelve a pedir la contraseña de login en cada corrida

Si un kovra recién recompilado sigue pidiendo la contraseña del login keychain para leer la master key, dar al binario acceso permanente: en Keychain Access, buscar el ítem kovra / master-key (master-key.<…> para un vault en otra carpeta, vea Configuración), y bajo Access Control permitir la aplicación kovra (o “Allow all applications”). Esto ocurre porque un binario firmado ad-hoc obtiene una identidad de código nueva en cada recompilación. La app firmada de kovra.sh conserva la misma identidad entre actualizaciones, así que lo pide a lo sumo una vez: al pasar de un build ad-hoc anterior al primero firmado (elija Permitir siempre).

El modo passphrase (KOVRA_PASSPHRASE) no es una salida en una Mac: kovra lo rechaza ahí y mantiene la clave en el Keychain.

KOVRA_KEYCHAIN_BIOMETRIC rechazada

KOVRA_KEYCHAIN_BIOMETRIC le pide al propio Keychain que exija Touch ID en cada lectura de la master key. La app de kovra que se descarga de kovra.sh todavía no puede crear un ítem así (necesita un permiso con el que la app no está firmada), así que se detiene con un error antes de tocar el Keychain, y nada cambia en su vault. Quite la variable (y bórrela de su perfil de shell) y ejecute el comando otra vez. Sus aprobaciones siguen pidiendo Touch ID como siempre: esta variable solo agrega un segundo prompt en el Keychain.

kovra no puede leer la master key del Keychain

• El keychain está bloqueado, o no se puede mostrar ningún diálogo (por ejemplo por SSH, donde el login keychain sigue bloqueado): ejecute el comando desde el escritorio de la Mac, con su sesión iniciada, para que macOS pueda desbloquear el keychain, o desbloquéelo en esa sesión con security unlock-keychain ~/Library/Keychains/login.keychain-db.
• Usted canceló el prompt del Keychain: ejecute el comando otra vez y permítalo.

kovra nunca toma una lectura fallida por una clave que falta: kovra init se detiene en lugar de crear una nueva.

command not found: kovra

El comando no está en su PATH. En macOS, abra kovra.app y elija Install Command Line Tool… en su menú de la barra de menús: crea /usr/local/bin/kovra, que apunta a la app (macOS pide la contraseña de un administrador). kovra setup y kovra doctor le avisan cuando el kovra de su PATH falta o es otro build.

Claude Code también lo necesita: el servidor MCP (kovra mcp) y los hooks del gate de credenciales se registran como kovra …, sin ruta.

El agente no ve las herramientas de kovra

Después de kovra setup, recargue el agente para que vuelva a leer .mcp.json. Confirme que el servidor está registrado ahí ("command": "kovra", "args": ["mcp"]) y que kovra está en su PATH (which kovra); en Claude Code, /mcp muestra si kovra está conectado. El agente solo ve metadatos con scope — si una coordenada queda fuera de su scope, es no direccionable, por diseño.

«This Claude Code session is not protected by kovra’s hooks»

Dentro de una sesión de Claude Code, kovra entrega valores (kovra run, show, code, decrypt; inject_run y reveal por MCP) solo si la configuración de la sesión tiene los hooks del gate de credenciales. Ejecute kovra setup en el proyecto; Claude Code toma los hooks sin reiniciar. Si el motivo menciona disableAllHooks o la configuración administrada, consulte Sin hooks, no hay valores.

Todos los prompts se bloquean, o la salida de las herramientas llega como [REDACTED:kovra-unavailable]

El gate de credenciales no obtuvo respuesta de kovrad y falló cerrado. El mensaje dice por qué:

• «kovrad is not running and did not start»: ejecute kovra daemon start, verifíquelo con kovra daemon status y envíe el prompt otra vez. Si kovrad se sigue deteniendo, kovra daemon install lo vuelve a registrar para que arranque al iniciar sesión.
• «kovrad is running but did not answer in time»: kovrad corre, pero la Mac está muy cargada. Espere un momento y envíe el prompt otra vez; si sigue pasando, reinicie kovrad con kovra daemon stop y kovra daemon start.

También falla cerrado cuando el proceso que responde en el endpoint de kovrad no es el kovrad firmado por Kaeus, o por las demás razones de Cuando kovrad no puede responder.

kovra daemon status dice que launchd no tiene kovrad

En una Mac, kovrad arranca al iniciar sesión por medio de launchd. Cuando está registrado pero launchd no lo tiene, kovra daemon status, kovra setup y kovra doctor agregan una nota que dice por qué:

• «turned off in System Settings»: kovrad está apagado en Ajustes → General → Ítems de inicio → Permitir en segundo plano. Enciéndalo ahí para que arranque al iniciar sesión. Mientras tanto, kovra lo arranca solo cuando lo necesita y no lo reinicia si se detiene.
• «its registration failed»: kovrad está permitido, pero launchd no lo cargó, por ejemplo después de actualizar kovra.app. Ejecute kovra daemon install: lo vuelve a cargar y termina cuando kovrad ya está corriendo.
• Cuando macOS no dice cuál de las dos es (antes de macOS 13), la nota da las dos causas: revise primero el interruptor y, si está encendido, ejecute kovra daemon install.

Un secreto no se revela

Los secretos inject-only nunca se revelan — solo pueden inyectarse. Los secretos high y prod nunca se revelan a un agente, y se revelan en la CLI solo tras un bioProve. Esto es la política funcionando como se pretende, no un bug; ver Niveles de sensibilidad.