Configuración

Esta es la referencia completa de cómo se configura kovra: las variables de entorno que lee y los archivos que usa.

Variables de entorno

Variable	Por defecto	Qué hace
`KOVRA_VAULT_DIR`	`~/.vaults`	Sobrescribe la raíz del registro de vaults. Un vault en otra carpeta guarda su master key en un ítem propio del Keychain (abajo).
`KOVRA_PASSPHRASE`	(sin definir)	Cambia al modo passphrase: deriva la master key con Argon2id en lugar de usar el keyring del OS. Se rechaza en macOS.
`KOVRA_CONFIRMER`	builds de desarrollo: `biometric` (recae en `file`)	Canal de confirmación: `biometric` (Touch ID) o `file` (el broker de `kovra approve`). Solo en builds de desarrollo: el kovra publicado para Mac siempre pide Touch ID o la contraseña de su sesión, y toda build la ignora dentro de una sesión de Claude Code.
`KOVRA_UI_NO_CONFIRM`	(sin definir)	Omite la confirmación de lanzamiento del Dashboard (igual que `kovra ui --no-confirm`).
`KOVRA_MCP_ENVIRONMENTS`	`*`	Scope de la sesión MCP — entornos direccionables (lista por comas, o `*` para cualquiera).
`KOVRA_MCP_PROJECTS`	`*`	Scope de la sesión MCP — proyectos direccionables (lista por comas, o `*` para cualquiera).

El directorio del vault

La raíz del registro (por defecto ~/.vaults, o KOVRA_VAULT_DIR) contiene:

~/.vaults/
  global/            # the global vault — sealed per-secret records + a sealed index
  projects/
    <name>/          # one directory per project vault, same layout
  keycheck.sec       # the key check: kovra refuses a master key that does not open it
  allowlist.sec      # the executor allowlist, sealed under the master key
  kdf.salt           # passphrase-mode only: the non-secret Argon2 salt

Cada registro está sellado en reposo; las coordenadas no se exponen como nombres de archivo en texto plano. Ver Criptografía para el formato en reposo.

La master key en el Keychain

Cada carpeta de vault guarda su master key en un ítem propio del Keychain (el Administrador de credenciales en Windows), bajo el servicio kovra:

~/.vaults usa el ítem master-key, como en todas las versiones de kovra.
Un vault en otra carpeta (KOVRA_VAULT_DIR) usa master-key.<…>, 16 caracteres derivados de la ruta de la carpeta. Un vault que usted crea para probar algo nunca toca la clave de su vault real: su kovra init --force o kovra key import --force reemplaza solo su propio ítem.
Después de actualizar, un vault en otra carpeta que hasta ahora usaba master-key adopta esa clave en su propio ítem, una sola vez, y solo si la clave abre todos sus registros. kovra lo avisa una vez; master-key queda como estaba. Un vault que todavía no guarda nada no la adopta: su kovra init crea una clave propia.
Si mueve la carpeta de un vault, el vault ya no encuentra su ítem en la ruta nueva. Ejecute kovra key export antes de moverla y kovra key import después.

Cuando borra la carpeta de un vault, su ítem master-key.<…> queda en el Keychain. No abre ningún vault que siga existiendo.

`.mcp.json`

kovra setup registra aquí el servidor MCP para que el agente pueda lanzarlo. El bloque env lleva el scope de la sesión MCP:

{
  "mcpServers": {
    "kovra": {
      "command": "kovra",
      "args": ["mcp"],
      "env": {
        "KOVRA_MCP_ENVIRONMENTS": "dev,test",
        "KOVRA_MCP_PROJECTS": "my-app"
      }
    }
  }
}

Esto es lo que limita lo que un agente sobre MCP puede direccionar (* = cualquiera). Es distinto de agent.toml, que da scope al ssh-agent.

`agent.toml` — el scope del ssh-agent

El ssh-agent gobernado lee su scope desde <vault-root>/agent.toml. El formato es deliberadamente diminuto — dos claves de array, con comentarios #:

# <vault-root>/agent.toml — kovra ssh-agent scope
environments = ["dev", "test"]   # omit (or []) → any environment
projects     = ["api"]           # omit (or []) → global + any project

Dos cosas no son configurables aquí, por diseño: el conjunto de operaciones está fijado a metadata + inject (un ssh-agent nunca revela una clave privada), y cuando el archivo está ausente el agente sirve cualquier entorno/proyecto — sin revelar nunca, y exigiendo igual un bioProve en cada firma high/prod.

La gramática de `.env.refs`

.env.refs mapea nombres locales de variables de entorno a fuentes. Contiene direcciones, nunca valores, así que es seguro commitearlo. Un mapeo por línea:

Forma	Significado
`project = <name>`	Vincula el archivo a un vault de proyecto (la resolución apunta a él).
`NAME=secret:<env>/<comp>/<key>`	Una coordenada de vault. Puede usar `${ENV}`; un `\| fallback` opcional aplica si no resuelve.
`NAME=secret://global/<env>/<comp>/<key>`	Fuerza la resolución contra el vault global, evitando el proyecto.
`NAME=${env:VAR}`	Un passthrough del entorno de ejecución. Soporta `${env:VAR \| fallback}`.
`NAME=literal`	Un valor literal (no un secreto), p. ej. `PORT=8080`.

Reglas que lo mantienen seguro:

Nunca valores — solo direcciones, así que un .env.refs filtrado no expone nada.
${ENV} lo sustituye kovra run --env <e> dentro del segmento de entorno de una coordenada; ${env:VAR} lee del entorno circundante.
La interpolación entre variables se rechaza — no se puede componer un secreto dentro del string de otra variable (ese string compuesto quedaría registrado).
La resolución es una única pasada ordenada sobre el archivo.

Ver El contrato de .env.refs para la versión narrativa.