Inicio rápido

Esta guía te lleva desde una máquina vacía hasta un secreto que tus herramientas pueden usar pero nunca ver. Asume que ya instalaste kovra.

Cada bloque de comandos tiene un selector de OS en su encabezado. Elige macOS o Windows una vez y todos los bloques de la página lo seguirán — tu elección se recuerda la próxima vez. macOS en Apple Silicon es la plataforma de referencia; Windows está en el roadmap, por lo que sus bloques muestran la experiencia prevista.

1. Inicializar la bóveda

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

Esto crea el registro de la bóveda y una clave maestra por bóveda, custodiada en el keychain del OS (macOS Keychain o Windows Credential Manager). La clave maestra cifra cada entrada en reposo; nunca la manejas directamente.

2. Almacenar un secreto

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

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

(¿Scripting? Pasa el valor por stdin con kovra add secret:dev/db/password --stdin.) Sin la bandera --sensitivity, un secreto nace como medium; puedes establecer un nivel y una descripción de forma explícita:

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

Lista lo almacenado — solo metadatos, nunca valores:

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

El fingerprint es un hash corto y truncado — suficiente para confirmar “mismo valor que antes”, pero nunca suficiente para reconstruirlo. Filtra con kovra list --env dev o --component app.

Si alguna vez necesitas recuperar un valor en la terminal, kovra show revela exactamente una coordenada. Un secreto ordinario se imprime de inmediato:

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

Un secreto high o prod primero solicita un bioProve (Touch ID en macOS, Windows Hello en Windows); consulta el paso 3. Los secretos más protegidos (inject-only) nunca se revelan — solo pueden inyectarse.

3. Inyectar secretos en un proceso

Las herramientas no deben leer la bóveda directamente — obtienen los valores mediante inyección. Describes el mapeo una sola vez en un archivo .env.refs que puede commitearse y que contiene direcciones, no valores:

#.env.refs — safe to commit; contains no secret values.
project = my-app

# Vault-backed, parameterized by --env (${ENV} is substituted at run time).
DATABASE_URL=secret:${ENV}/db/password
API_KEY=secret:${ENV}/app/api-key

# Passthrough from the environment, with a fallback if unset.
LOG_LEVEL=${env:LOG_LEVEL | info}

# A plain literal (not a secret).
PORT=8080

Luego ejecuta cualquier comando con los valores resueltos inyectados directamente en el proceso hijo — nada se escribe en disco, argv ni en el historial del shell:

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

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

Producción añade dos barreras

Cambia el entorno a prod y el mismo comando se somete a un estándar más exigente — un secreto prod nace como high, y una inyección high/prod está gobernada por dos barreras independientes: debe apuntar a un ejecutable en la lista de permitidos, y se detiene para un bioProve. Ejecútalo contra un programa no revisado y kovra lo rechaza, por diseño:

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

Agrega el ejecutable revisado a la lista con --allow y realiza el bioProve (una confirmación cubre todos los secretos de la ejecución):

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

El camino conveniente es el seguro

Los secretos de desarrollo se inyectan sin fricción; producción no puede inyectarse en un programa que el agente (o tú) no revisó, y nunca sin una confirmación deliberada. Esa asimetría es precisamente el punto.

¿No sabes qué necesita tu repositorio? Deja que kovra proponga un .env.refs analizando tu código fuente en busca de referencias a variables de entorno (solo lee los nombres de las variables — nunca un valor):

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

4. Conectar Claude Code

Incorpora el repositorio actual para que un agente de IA pueda usar tus secretos sin ver los sensibles:

macOS

zsh

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

Windows

Windows — próximamente. Credential Manager + Windows Hello, el mismo modelo de seguridad.

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 metadatos con alcance limitado — que existe un secreto, su sensibilidad, su coordenada — y puede ejecutar comandos a través del wrapper, pero el texto plano de tus secretos high / prod / inject-only nunca entra en el contexto del modelo.

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

Hacia dónde ir ahora

Ahora tienes el ciclo completo: almacenar → inyectar → delegar a un agente, con el texto plano sensible sin salir jamás de la bóveda. Desde aquí:

• Descripción general — el mapa de conceptos: coordenadas, niveles de sensibilidad, alcance del agente y el contrato de .env.refs.
• Cómo funciona — los flujos cotidianos de principio a fin, en un nivel alto.
• Los 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.