agents-vault

Un único libro mayor para cada cuenta, clave y router de Claude Code, Codex y Grok, cada uno abierto con la sesión iniciada en su propia carpeta home.

Rustversatile.shcódigo disponible (GPL-3.0-or-later)Lenguaje Rust 1.89+Licencia GPL-3.0-or-laterBinarios vvault, vvault-app (bandeja Tauri)Plataformas Linux, macOS, Windowsgithub.com/versatile-sh/agents-vault

Visión general

agents-vault mantiene un libro mayor de cada cuenta, clave de API y router de Claude Code, Codex y Grok que usas. Eliges una cuenta y se abre una terminal con la sesión ya iniciada, en el modelo correcto y con tus instrucciones compartidas en su sitio. Un icono en la bandeja muestra los límites de 5 horas y semanales de cada cuenta.

El problema que elimina es compartir credenciales entre cuentas. Cada cuenta tiene su propia carpeta home, así que un refresh token que rota existe en un solo lugar. Nunca guarda, copia ni renueva un token OAuth: el inicio de sesión, la renovación y el cierre de sesión quedan en manos de claude, codex y grok.

Corre en tu máquina como un workspace de Rust: una librería core, el comando vvault y una app de bandeja Tauri. No está afiliado a Anthropic, OpenAI ni xAI.

Crate o rutaFunción
crates/corelibro mayor, lanzador, llavero, límites, keep-alive
crates/cliel comando vvault
app/src-tauribackend de la app de bandeja
app/uiinterfaz de la bandeja en HTML, CSS y JS simples, sin paso de build

Instalar y ejecutar

Requisitos: Rust 1.89 o posterior y, para la app de bandeja, las dependencias de sistema de Tauri 2.

pon vvault-app junto a vvault, o deja vvault en el PATH; los instaladores salen de cargo tauri build en app/src-taurish
git clone https://github.com/versatile-sh/agents-vault
cd agents-vault
cargo install --path crates/cli
cargo build --release -p vvault-app --features custom-protocol

Con un libro mayor nuevo, vvault list responde: No accounts yet. Try `vvault add work` or `vvault adopt personal`.

sh
vvault add work                       # official Claude Code sign-in
vvault add team --harness codex       # official Codex sign-in
vvault add x --harness grok           # official Grok sign-in
vvault adopt personal                 # track your existing ~/.claude in place
vvault list
vvault open work                      # new terminal window on that account
vvault run work -- --resume           # same, in the current terminal
vvault default work                   # plain `claude` now means the work account
sh
vvault add router --base-url https://openrouter.ai/api --bearer --model vendor/model
vvault provider add OpenRouter --preset openrouter --model vendor/model-a
vvault use OpenRouter --with codex --model vendor/model-b
vvault kit claude --dir ~/.claude
vvault keepalive                      # exit code 1 when an account needs a new sign-in
vvault waybar                         # JSON for a status bar
VariablePor defectoEfecto
VVAULT_HOMEla carpeta de datos de la plataformamueve el libro mayor, para mantener los experimentos lejos de las cuentas reales
sh
mise run check            # rustfmt, clippy, tests, Semgrep
mise run test             # cargo test --workspace
mise run dev -- list      # the CLI against a throwaway ledger in /tmp/vvault-dev

Arquitectura

trayvvaultledgeracctacctacctclaudecodexgrok
La bandeja y la CLI comparten un store, que guarda un casillero privado por cuenta y arranca cada harness desde el suyo.

crates/core contiene todo el comportamiento. La CLI y el backend de Tauri son front ends finos sobre el mismo Store y las mismas funciones, así que la app de bandeja y vvault siempre coinciden.

text
tray app / vvault CLI
        |
        v
   store::Store  --- ledger.json (labels, models, paths; 0600)
        |             profiles/<id>/   (one harness home per account)
        |             limits/ status/ balance/ caches
        v
   launch::plan  --- secrets (OS keychain, read last)
        |
        v
   claude | codex | grok   with CLAUDE_CONFIG_DIR / CODEX_HOME / GROK_HOME
  • model.rs: Harness (Claude, Codex, Grok), Auth (Login o ApiKey), Account, Config, Provider.
  • launch.rs: construye el Launch (programa, args, env) y limpia el entorno heredado.
  • limits.rs, status.rs, balance.rs, claude.rs, codex.rs: leen límites, estado de sesión y saldos por harness.
  • kit.rs: enlaza instrucciones compartidas en los perfiles. machine.rs: la cuenta por defecto de toda la máquina.
  • terminal.rs: abre una ventana de terminal que reentra mediante vvault run.

Abrir una cuenta

vvault runiddroppedhomekeychainat launchharness
Las variables de identidad se descartan en una compuerta y la clave sale del llavero solo en el lanzamiento.
  1. 1ElegirEliges una cuenta en la app de bandeja o ejecutas vvault open. La terminal ejecuta vvault run <id>, así que la clave se resuelve dentro de ese proceso.
  2. 2Validarlaunch::plan llama a Account::validate, y luego ensure_home crea el directorio del perfil, privado para el usuario.
  3. 3LimpiarSe eliminan las variables heredadas que anulan la identidad: ANTHROPIC_*, CLAUDE_CODE_OAUTH_*, CLAUDE_CODE_USE_*, CLAUDE_CONFIG_DIR, CODEX_HOME, CODEX_API_KEY, CODEX_ACCESS_TOKEN, GROK_HOME, XAI_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL.
  4. 4Resolver la claveEn una cuenta con clave de API, la clave se lee del llavero del SO en ese momento y se pasa solo por el entorno.
  5. 5LanzarEl harness arranca con la variable home de la cuenta, los argumentos de modelo y las entradas del kit enlazadas en el perfil.

Por harness, una clave de API llega como ANTHROPIC_API_KEY, o ANTHROPIC_AUTH_TOKEN con --bearer, para Claude; como VVAULT_API_KEY leída por un provider definido con flags -c para Codex; y como XAI_API_KEY para Grok. Codex necesita un endpoint que hable la Responses API.

Libro mayor y store

store::Store abre VVAULT_HOME o el directorio de datos de la plataforma (project dirs sh/versatile/vvault). La raíz se crea con modo 0700 y ledger.json se escribe con 0600.

  • Store::update toma un lock exclusivo sobre .lock, carga el libro mayor, aplica tu closure, valida cada cuenta y provider, y escribe mediante write_json.
  • write_json escribe un archivo temporal privado en el mismo directorio, llama a sync_all y lo renombra sobre ledger.json, así que un crash nunca deja un libro mayor a medio escribir.
  • Campos de una cuenta: id (UUID), label (1 a 80 caracteres, sin caracteres de control), harness, auth, model, fast_model, home, native_home, env, args, kit.
  • El home de una cuenta gestionada es profiles/<id>. Las cuentas native_home usan la carpeta propia del harness, como hace adopt, y nunca se copian.
  • Las cachés viven en archivos por id como limits/<id>.json; el id debe interpretarse como UUID, lo que bloquea trucos de rutas.
  • Los labels son únicos sin distinguir mayúsculas, y se comprueba de nuevo dentro del update con lock.

Límites y keep-alive

statususagebalancesession / weeklykeep-alive
Las lecturas de uso llenan un libro mayor con medidores de sesión y semanales por cuenta, mantenidos al día por un reloj de keep-alive.
CuentaFuenteFrescura
Inicio de sesión de Claude Codeendpoints de cuenta de Anthropic, más los rate_limits que Claude Code envía a su status linetras iniciar sesión, luego como máximo una vez por minuto
Inicio de sesión de Codexlas peticiones account/read y account/rateLimits/read de la CLI de Codextras iniciar sesión, luego como máximo una vez por minuto
Inicio de sesión de Groksolo estado de sesiónninguna
Claves de OpenRouter, DeepSeekla petición de clave o saldo del providercomo máximo cada dos minutos
  • Los límites tienen una Window de sesión y una semanal (percent 0 a 100, resets_at). settled pone a cero cualquier ventana cuya hora de reinicio ya pasó.
  • La status line se inyecta con --settings en el lanzamiento, así que tu settings.json no se modifica. Una status line existente sigue ejecutándose.
  • status.rs cachea el estado de login y lo vuelve a comprobar a los 50 minutos; keepalive renueva las cuentas inactivas pidiendo a cada harness su propio estado.
  • En macOS, Claude Code guarda su sesión en el Keychain, así que allí los límites de Claude vienen solo de la status line.

Modelo de seguridad

acct 1acct 2no copykeychainkeyhttp: refusedhttps
Un casillero por cuenta, sin copias, las claves se quedan en el llavero y el http plano se rechaza.
ReglaSignificado
Un home por cuentalas credenciales nunca se copian entre carpetas
El harness es dueño de sus tokensel inicio de sesión, la renovación y el cierre los hace el harness
Claves en el llavero del SOmacOS Keychain, Windows Credential Manager o Secret Service, bajo el servicio vvault; nunca en el libro mayor, un archivo de configuración ni una línea de comandos
Claves resueltas al finalse leen dentro de vvault run y se pasan por entorno
Texto claro rechazadoun endpoint personalizado debe ser https://, http:// plano solo para localhost, 127.0.0.1 o [::1]
Sin reutilizar clavesse rechaza un valor env extra que repita la clave de API

Una excepción de solo lectura: para mostrar los límites de Claude y el nombre del plan, el access token que guardó Claude Code se lee en memoria y se envía solo a los endpoints de cuenta de Anthropic (api.anthropic.com/api/oauth/usage y /profile). No están documentados; si cambian, los límites recurren a la status line.

Decisiones y límites

DecisiónElegidoDescartadoPor qué
Manejo de tokensnunca tocar los tokens OAuthcopiarlos o renovarlosun refresh token que rota debe vivir en un solo lugar
Aislamientouna carpeta home por cuenta mediante CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOMEcambiar credenciales dentro de una carpetasin copias, una sola sesión
Cuenta por defecto de la máquinaapuntar el harness al home de la cuentacopiar la cuenta al home por defectono se copia nada; solo cuentas de login, ya que una clave quedaría en cada shell
Entrega de claveslectura del llavero en el lanzamiento, solo por entornoguardar claves en el libro mayor o en flagslas claves quedan fuera de archivos y líneas de comandos
Escrituras del libro mayorcon lock, validadas, renombrado atómicosobrescritura simpleningún libro mayor a medias ni inválido
UIHTML, CSS, JS simplesun build de frontendsin paso de build para la app de bandeja
  • Los límites de Grok no se informan: la CLI de Grok solo expone el estado de sesión.
  • Las cuentas de Grok usan el endpoint de xAI; un endpoint personalizado se rechaza.
  • Los endpoints de uso y perfil de Anthropic no están documentados y pueden cambiar.
  • Las terminales ya abiertas conservan su cuenta hasta que ejecutes eval "$(vvault env)" o las reabras.
  • No se publican números de rendimiento medidos para este proyecto.

Archivos para leer