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.
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 ruta | Función |
|---|---|
| crates/core | libro mayor, lanzador, llavero, límites, keep-alive |
| crates/cli | el comando vvault |
| app/src-tauri | backend de la app de bandeja |
| app/ui | interfaz 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.
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-protocolCon un libro mayor nuevo, vvault list responde: No accounts yet. Try `vvault add work` or `vvault adopt personal`.
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 accountvvault 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| Variable | Por defecto | Efecto |
|---|---|---|
| VVAULT_HOME | la carpeta de datos de la plataforma | mueve el libro mayor, para mantener los experimentos lejos de las cuentas reales |
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-devArquitectura
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.
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
- 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.
- 2Validarlaunch::plan llama a Account::validate, y luego ensure_home crea el directorio del perfil, privado para el usuario.
- 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.
- 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.
- 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
| Cuenta | Fuente | Frescura |
|---|---|---|
| Inicio de sesión de Claude Code | endpoints de cuenta de Anthropic, más los rate_limits que Claude Code envía a su status line | tras iniciar sesión, luego como máximo una vez por minuto |
| Inicio de sesión de Codex | las peticiones account/read y account/rateLimits/read de la CLI de Codex | tras iniciar sesión, luego como máximo una vez por minuto |
| Inicio de sesión de Grok | solo estado de sesión | ninguna |
| Claves de OpenRouter, DeepSeek | la petición de clave o saldo del provider | como 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
| Regla | Significado |
|---|---|
| Un home por cuenta | las credenciales nunca se copian entre carpetas |
| El harness es dueño de sus tokens | el inicio de sesión, la renovación y el cierre los hace el harness |
| Claves en el llavero del SO | macOS 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 final | se leen dentro de vvault run y se pasan por entorno |
| Texto claro rechazado | un endpoint personalizado debe ser https://, http:// plano solo para localhost, 127.0.0.1 o [::1] |
| Sin reutilizar claves | se 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ón | Elegido | Descartado | Por qué |
|---|---|---|---|
| Manejo de tokens | nunca tocar los tokens OAuth | copiarlos o renovarlos | un refresh token que rota debe vivir en un solo lugar |
| Aislamiento | una carpeta home por cuenta mediante CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME | cambiar credenciales dentro de una carpeta | sin copias, una sola sesión |
| Cuenta por defecto de la máquina | apuntar el harness al home de la cuenta | copiar la cuenta al home por defecto | no se copia nada; solo cuentas de login, ya que una clave quedaría en cada shell |
| Entrega de claves | lectura del llavero en el lanzamiento, solo por entorno | guardar claves en el libro mayor o en flags | las claves quedan fuera de archivos y líneas de comandos |
| Escrituras del libro mayor | con lock, validadas, renombrado atómico | sobrescritura simple | ningún libro mayor a medias ni inválido |
| UI | HTML, CSS, JS simples | un build de frontend | sin 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
- README.mdinstalación, uso, configuración, estructura
- docs/usage.mdvalores por defecto, providers, kit, límites, modelos, keep-alive
- docs/safety.mdlas reglas de seguridad completas
- crates/core/src/model.rsHarness, Auth, Account y validación
- crates/core/src/store.rsraíz del libro mayor, locking, escrituras atómicas
- crates/core/src/launch.rslimpieza del entorno y plan de lanzamiento por harness
- crates/core/src/secrets.rsacceso al llavero
- crates/core/src/limits.rsventanas de límites y throttling de sondeos
- crates/core/src/status.rsestado de sesión y keep-alive
- crates/core/src/machine.rscuenta por defecto de toda la máquina
- crates/cli/src/main.rsla superficie del comando vvault
- app/src-tauri/src/main.rscomandos de la app de bandeja