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.

Cada caja de comandos tiene un selector de OS en su encabezado. Al elegir macOS o Windows una vez, todas las cajas de la página siguen esa elección — queda recordada para la próxima. macOS en Apple Silicon es la plataforma de referencia; Windows está en Beta (mismos comandos, Windows Hello + Credential Manager) — ver Soporte de plataformas.

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

PS C:\my-app> kovra init
Initialized vault at %LOCALAPPDATA%\kovra\vaults (Credential Manager).

Esto crea el registro de vaults y una master key por vault, custodiada en el keychain del SO (el Keychain de macOS o el Credential Manager de Windows). 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:

macOS
Windows

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

PS C:\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:

macOS
Windows

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

PS C:\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:

macOS
Windows

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

PS C:\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. 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:

macOS
Windows

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

PS C:\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 en macOS, Windows Hello en Windows); 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:

macOS
Windows

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

PS C:\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:

macOS
Windows

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

PS C:\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):

macOS
Windows

~/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

PS C:\my-app> kovra run --env prod --allow .\deploy -- .\deploy
# Windows Hello 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):

macOS
Windows

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

PS C:\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:

macOS
Windows

~/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).
Setup complete. Review CLAUDE.md and .mcp.json, then reload your agent to pick up the MCP server.

PS C:\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).
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.

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. Desde acá:

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.