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.
KOVRA_PASSPHRASE	(sin definir)	Cambia al modo passphrase: deriva la master key con Argon2id en lugar de usar el keyring del OS.
KOVRA_CONFIRMER	biometric (recae en file)	Canal de confirmación: biometric (Touch ID / Windows Hello) o file (el broker de kovra approve).
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
  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.

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