agents-vault

One ledger for every Claude Code, Codex and Grok account, key and router, each opened signed in on its own home folder.

Rustversatile.shsource-available (GPL-3.0-or-later)Language Rust 1.89+License GPL-3.0-or-laterBinaries vvault, vvault-app (Tauri tray)Platforms Linux, macOS, Windowsgithub.com/versatile-sh/agents-vault

Overview

agents-vault keeps a ledger of every Claude Code, Codex and Grok account, API key and router you use. Pick an account and a terminal opens already signed in, on the right model, with your shared instructions in place. A tray icon shows each account's 5-hour and weekly limits.

The problem it removes is credential sharing between accounts. Every account gets its own home folder, so a rotating refresh token only ever exists in one place. It never stores, copies or refreshes an OAuth token: sign-in, refresh and sign-out stay with claude, codex and grok themselves.

It runs on your machine as a Rust workspace: a core library, the vvault command and a Tauri tray app. It is not affiliated with Anthropic, OpenAI or xAI.

Crate or pathRole
crates/coreledger, launcher, keychain, limits, keep-alive
crates/clithe vvault command
app/src-tauritray app backend
app/uitray interface in plain HTML, CSS and JS, no build step

Install and run

Prerequisites: Rust 1.89 or later and, for the tray app, the Tauri 2 system dependencies.

put vvault-app next to vvault, or keep vvault on PATH; installers come from cargo tauri build in 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

With a fresh ledger, vvault list answers: 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
VariableDefaultEffect
VVAULT_HOMEthe platform data foldermoves the ledger, to keep experiments away from real accounts
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

Architecture

trayvvaultledgeracctacctacctclaudecodexgrok
Tray and CLI share one store, which keeps a private locker per account and starts each harness from its own.

crates/core holds all behavior. The CLI and the Tauri backend are thin front ends over the same Store and functions, so the tray app and vvault always agree.

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 or ApiKey), Account, Config, Provider.
  • launch.rs: builds the Launch (program, args, env) and scrubs the inherited environment.
  • limits.rs, status.rs, balance.rs, claude.rs, codex.rs: read limits, session state and balances per harness.
  • kit.rs: links shared instructions into profiles. machine.rs: the machine-wide default account.
  • terminal.rs: opens a terminal window that re-enters through vvault run.

Opening an account

vvault runiddroppedhomekeychainat launchharness
Identity variables are dropped at a gate and the key leaves the keychain only at launch.
  1. 1PickYou choose an account in the tray app or run vvault open. The terminal runs vvault run <id>, so the key is resolved inside that process.
  2. 2Validatelaunch::plan calls Account::validate, then ensure_home creates the profile directory private to the user.
  3. 3ScrubInherited variables that override identity are removed: 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. 4Resolve the keyFor an API key account, the key is read from the OS keychain at that moment and passed through the environment only.
  5. 5LaunchThe harness starts with the account's home variable, model arguments and any kit entries linked into the profile.

Per harness, an API key arrives as ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN with --bearer, for Claude; as VVAULT_API_KEY read by a provider defined with -c flags for Codex; and as XAI_API_KEY for Grok. Codex needs an endpoint that speaks the Responses API.

Ledger and store

store::Store opens VVAULT_HOME or the platform data directory (project dirs sh/versatile/vvault). The root is created mode 0700 and ledger.json is written 0600.

  • Store::update takes an exclusive lock on .lock, loads the ledger, applies your closure, validates every account and provider, then writes through write_json.
  • write_json writes a private temporary file in the same directory, calls sync_all and renames it over ledger.json, so a crash never leaves a half-written ledger.
  • Account fields: id (UUID), label (1 to 80 chars, no control characters), harness, auth, model, fast_model, home, native_home, env, args, kit.
  • A managed account's home is profiles/<id>. native_home accounts use the harness's own folder, as adopt does, and are never copied.
  • Caches live in per-id files such as limits/<id>.json; the id must parse as a UUID, which blocks path tricks.
  • Labels are unique case-insensitively, checked again inside the locked update.

Limits and keep-alive

statususagebalancesession / weeklykeep-alive
Usage readings fill a ledger with session and weekly gauges per account, kept fresh by a keep-alive clock.
AccountSourceFreshness
Claude Code sign-inAnthropic account endpoints, plus rate_limits that Claude Code sends to its status lineafter sign-in, then at most once a minute
Codex sign-inthe Codex CLI's account/read and account/rateLimits/read requestsafter sign-in, then at most once a minute
Grok sign-insession state onlynone
OpenRouter, DeepSeek keysthe provider's key or balance requestat most every two minutes
  • Limits hold a session and a weekly Window (percent 0 to 100, resets_at). settled zeroes any window whose reset time has passed.
  • The status line is injected with --settings at launch, so your settings.json is not modified. An existing status line keeps running.
  • status.rs caches login state and re-checks after 50 minutes; keepalive renews idle accounts by asking each harness for its own status.
  • On macOS Claude Code keeps its sign-in in the Keychain, so there Claude limits come only from the status line.

Safety model

acct 1acct 2no copykeychainkeyhttp: refusedhttps
One locker per account, no copying, keys stay in the keychain, and plain http is refused.
RuleMeaning
One home per accountcredentials are never copied between folders
The harness owns its tokenssign-in, refresh and sign-out are done by the harness
Keys in the OS keychainmacOS Keychain, Windows Credential Manager or Secret Service, under service vvault; never in the ledger, a config file or a command line
Keys resolved lateread inside vvault run and passed by environment
Clear text refuseda custom endpoint must be https://, plain http:// only for localhost, 127.0.0.1 or [::1]
No key reusean extra env value that repeats the API key is refused

One read-only exception: to show Claude limits and the plan name, the access token Claude Code saved is read in memory and sent only to Anthropic's account endpoints (api.anthropic.com/api/oauth/usage and /profile). They are undocumented; if they change, limits fall back to the status line.

Decisions and limits

DecisionChosenRejectedWhy
Token handlingnever touch OAuth tokenscopy or refresh thema rotating refresh token must live in one place
Isolationa home folder per account via CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOMEswapping credentials in one folderno copies, one session
Machine defaultpoint the harness at the account's homecopy the account into the default homenothing is copied; only login accounts, as a key would sit in every shell
Key deliverykeychain read at launch, environment onlystoring keys in the ledger or flagskeys stay out of files and command lines
Ledger writeslocked, validated, atomic renameplain overwriteno half-written or invalid ledger
UIplain HTML, CSS, JSa frontend buildno build step for the tray app
  • Grok limits are not reported: the Grok CLI exposes session state only.
  • Grok accounts use the xAI endpoint; a custom endpoint is refused.
  • Anthropic's usage and profile endpoints are undocumented and may change.
  • Terminals already open keep their account until you run eval "$(vvault env)" or reopen them.
  • No measured performance numbers are published for this project.

Files to read