Inicio rápido

Esto lleva de una máquina vacía a un secreto que las herramientas pueden usar pero nunca ver. Asume que kovra ya está instalado.

kovra 0.12.1 se entrega para macOS, así que los comandos de abajo se muestran en una terminal de macOS; Windows llegará próximamente — ver Soporte de plataformas.

1. Inicializar el vault

~/my-app % kovra init
Initialized vault at ~/.vaults (OS keyring).

Esto crea el registro de vaults y una master key por vault, custodiada en el Keychain de macOS. La master key cifra cada entrada en reposo; nunca se manipula directamente.

2. Guardar un secreto

Los secretos se direccionan con una coordenada de la forma secret:<env>/<componente>/<key>. kovra lee el valor desde un prompt oculto — nunca aparece en argv ni en el historial del shell:

~/my-app % kovra add secret:dev/db/password
Added dev/db/password (Medium).

(¿Scripting? Pasar el valor por pipe con kovra add secret:dev/db/password --stdin.) Sin el flag --sensitivity, un secreto nace medium; se puede fijar un nivel y una descripción de forma explícita:

~/my-app % kovra add secret:dev/app/api-key --description "App API key"
Added dev/app/api-key (Medium).

Listar lo guardado — solo metadata, nunca valores:

~/my-app % kovra list
┌────────┬─────────────────┬─────────────┬─────────┬─────────────┐
│ ORIGIN ┆ COORDINATE      ┆ SENSITIVITY ┆ MODE    ┆ FINGERPRINT │
╞════════╪═════════════════╪═════════════╪═════════╪═════════════╡
│ global ┆ dev/app/api-key ┆ medium      ┆ literal ┆ c8a476b5    │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ global ┆ dev/db/password ┆ medium      ┆ literal ┆ 73c128b4    │
└────────┴─────────────────┴─────────────┴─────────┴─────────────┘

El fingerprint es un hash corto y truncado — alcanza para confirmar “mismo valor que antes”, nunca para reconstruirlo. Los valores críticos — high, inject-only y todo lo que está en prod — muestran — en su lugar: ni siquiera un hash truncado. Filtrar con kovra list --env dev o --component app.

Si en algún momento hace falta un valor de vuelta en la terminal, kovra show revela exactamente una coordenada. Un secreto ordinario se imprime directo:

~/my-app % kovra show secret:dev/db/password
(revealing dev/db/password to stdout — ephemeral, not stored)
dev-db-pw-•••••

Un secreto high o prod primero pide un bioProve (Touch ID, o la contraseña de su sesión en una Mac sin Touch ID); ver paso 3. Los secretos más protegidos (inject-only) no se revelan nunca — solo se pueden inyectar.

3. Inyectar secretos en un proceso

Las herramientas no deberían leer el vault directamente — reciben los valores por inyección. El mapeo se describe una vez en un archivo .env.refs commiteable que contiene direcciones, no valores:

# .env.refs — seguro para commitear; no contiene valores secretos.
project = my-app

# Respaldado por el vault, parametrizado por --env (${ENV} se sustituye en runtime).
DATABASE_URL=secret:${ENV}/db/password
API_KEY=secret:${ENV}/app/api-key

# Passthrough desde el entorno, con un fallback si no está seteada.
LOG_LEVEL=${env:LOG_LEVEL | info}

# Un literal plano (no un secreto).
PORT=8080

Después correr cualquier comando con los valores resueltos inyectados directo en el proceso hijo — nada se escribe a disco, argv ni al historial del shell:

~/my-app % kovra run --env dev -- your-app
app started · DATABASE_URL=14 chars · API_KEY set=yes · PORT=8080

Con --env dev, ${ENV} resuelve a dev, así que DATABASE_URL se lee de secret:dev/db/password. Los valores llegan al entorno de la app y a ningún otro lado.

Producción suma dos guards

Al cambiar el entorno a prod, el mismo comando se mide con una vara más alta — un secreto prod nace high, y una inyección high/prod está gobernada por dos guards independientes: debe apuntar a un ejecutable en el allowlist, y se detiene a pedir un bioProve. Al correrlo contra un programa no revisado, kovra se niega, por diseño:

~/my-app % kovra run --env prod -- your-app
Error: `your-app` is not on the executor allowlist; high/prod injection refused

Agregar el ejecutable revisado al allowlist con --allow y hacer un bioProve (una sola confirmación cubre todos los secretos de la corrida):

~/my-app % kovra run --env prod --allow ./deploy -- ./deploy
# Touch ID prompt — approve to inject prod/db/password, prod/app/api-key
deploying with DATABASE_URL=12 chars, API_KEY set=yes

¿No está claro qué necesita el repo? kovra puede proponer un .env.refs escaneando el código en busca de referencias a variables de entorno (lee solo los nombres de las variables — nunca un valor):

~/my-app % kovra scaffold --out .env.refs
Wrote 2 proposed coordinate(s) to .env.refs — review before use.

4. Conectar Claude Code

Onboardear el repo actual para que un agente de IA pueda usar los secretos sin ver los sensibles:

~/my-app % kovra setup
Vault ready; project `my-app`.
Updated .mcp.json (register the kovra MCP server).
Updated CLAUDE.md (insert/update the kovra conventions block).
Updated .claude/settings.json (deny Read of secrets files).
Updated .claude/settings.local.json (install the credential gate's Claude Code hooks).
Credential gate: Claude Code now asks kovra before a prompt or a tool output
  reaches the model (it reloads hooks on its own). Notes:
  - Hooks fail closed on a crash only from Claude Code 2.1.295 (`onFailure`).
  - Recommended: set CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 in your user settings
    (~/.claude/settings.json, "env") or your shell (Claude Code 2.1.299+). Then
    @file mentions go through Read and the gate. Project settings ignore it, so
    kovra setup does not write it.
kovrad: registered to run at login.
Setup complete. Review CLAUDE.md and .mcp.json, then reload your agent to pick up the MCP server.

Esto registra el servidor MCP de kovra en ./.mcp.json y agrega un bloque de convenciones a ./CLAUDE.md. A partir de ahí, Claude Code ve metadata con scope — que un secreto existe, su sensibilidad, su coordenada — y puede correr comandos a través del wrapper, pero el texto plano de los secretos high / prod / inject-only nunca entra al contexto del modelo.

En macOS además instala el gate de credenciales: Claude Code le consulta a kovra antes de que un prompt o la salida de una herramienta lleguen al modelo, de modo que una credencial que usted pegue se bloquea y una que devuelva una herramienta se redacta.

Previsualizar los cambios sin escribir nada con kovra setup --dry-run.

Hacia dónde seguir

Ahora está el loop completo: guardar → inyectar → delegar a un agente, con el texto plano sensible sin salir nunca del vault. A partir de aquí:

Vista general — el mapa de conceptos: coordenadas, niveles de sensibilidad, scope del agente y el contrato .env.refs.
Cómo funciona — los flujos cotidianos de punta a punta, a alto nivel.
Secretos en la era de los agentes de IA — el whitepaper de kovra: el problema, las tensiones, la solución y un relato honesto de los riesgos y limitaciones de kovra.