agents-vault
One ledger for every Claude Code, Codex and Grok account, key and router, each opened signed in on its own home folder.
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 path | Role |
|---|---|
| crates/core | ledger, launcher, keychain, limits, keep-alive |
| crates/cli | the vvault command |
| app/src-tauri | tray app backend |
| app/ui | tray 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.
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-protocolWith a fresh ledger, vvault list answers: 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 | Default | Effect |
|---|---|---|
| VVAULT_HOME | the platform data folder | moves the ledger, to keep experiments away from real accounts |
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-devArchitecture
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.
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
- 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.
- 2Validatelaunch::plan calls Account::validate, then ensure_home creates the profile directory private to the user.
- 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.
- 4Resolve the keyFor an API key account, the key is read from the OS keychain at that moment and passed through the environment only.
- 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
| Account | Source | Freshness |
|---|---|---|
| Claude Code sign-in | Anthropic account endpoints, plus rate_limits that Claude Code sends to its status line | after sign-in, then at most once a minute |
| Codex sign-in | the Codex CLI's account/read and account/rateLimits/read requests | after sign-in, then at most once a minute |
| Grok sign-in | session state only | none |
| OpenRouter, DeepSeek keys | the provider's key or balance request | at 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
| Rule | Meaning |
|---|---|
| One home per account | credentials are never copied between folders |
| The harness owns its tokens | sign-in, refresh and sign-out are done by the harness |
| Keys in the OS keychain | macOS Keychain, Windows Credential Manager or Secret Service, under service vvault; never in the ledger, a config file or a command line |
| Keys resolved late | read inside vvault run and passed by environment |
| Clear text refused | a custom endpoint must be https://, plain http:// only for localhost, 127.0.0.1 or [::1] |
| No key reuse | an 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
| Decision | Chosen | Rejected | Why |
|---|---|---|---|
| Token handling | never touch OAuth tokens | copy or refresh them | a rotating refresh token must live in one place |
| Isolation | a home folder per account via CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME | swapping credentials in one folder | no copies, one session |
| Machine default | point the harness at the account's home | copy the account into the default home | nothing is copied; only login accounts, as a key would sit in every shell |
| Key delivery | keychain read at launch, environment only | storing keys in the ledger or flags | keys stay out of files and command lines |
| Ledger writes | locked, validated, atomic rename | plain overwrite | no half-written or invalid ledger |
| UI | plain HTML, CSS, JS | a frontend build | no 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
- README.mdinstall, usage, configuration, layout
- docs/usage.mddefaults, providers, kit, limits, models, keep-alive
- docs/safety.mdthe safety rules in full
- crates/core/src/model.rsHarness, Auth, Account and validation
- crates/core/src/store.rsledger root, locking, atomic writes
- crates/core/src/launch.rsenvironment scrub and per-harness launch plan
- crates/core/src/secrets.rskeychain access
- crates/core/src/limits.rslimit windows and probe throttling
- crates/core/src/status.rssession state and keep-alive
- crates/core/src/machine.rsmachine-wide default account
- crates/cli/src/main.rsthe vvault command surface
- app/src-tauri/src/main.rstray app commands