agents-vault

Um único livro-razão para cada conta, chave e router do Claude Code, Codex e Grok, cada um aberto já logado na sua própria pasta home.

Rustversatile.shcódigo disponível (GPL-3.0-or-later)Linguagem Rust 1.89+Licença GPL-3.0-or-laterBinários vvault, vvault-app (bandeja Tauri)Plataformas Linux, macOS, Windowsgithub.com/versatile-sh/agents-vault

Visão geral

O agents-vault mantém um livro-razão de cada conta, chave de API e router do Claude Code, Codex e Grok que você usa. Escolha uma conta e um terminal abre já logado, no modelo certo, com suas instruções compartilhadas no lugar. Um ícone na bandeja mostra os limites de 5 horas e semanais de cada conta.

O problema que ele elimina é o compartilhamento de credenciais entre contas. Cada conta tem sua própria pasta home, então um refresh token que rotaciona existe em um só lugar. Ele nunca guarda, copia nem renova um token OAuth: login, renovação e logout ficam com o claude, o codex e o grok.

Roda na sua máquina como um workspace Rust: uma biblioteca core, o comando vvault e um app de bandeja Tauri. Não é afiliado à Anthropic, OpenAI nem xAI.

Crate ou caminhoPapel
crates/corelivro-razão, launcher, keychain, limites, keep-alive
crates/clio comando vvault
app/src-tauribackend do app de bandeja
app/uiinterface da bandeja em HTML, CSS e JS puros, sem etapa de build

Instalar e rodar

Pré-requisitos: Rust 1.89 ou superior e, para o app de bandeja, as dependências de sistema do Tauri 2.

coloque o vvault-app ao lado do vvault, ou deixe o vvault no PATH; os instaladores vêm de cargo tauri build em 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

Com um livro-razão novo, 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
VariávelPadrãoEfeito
VVAULT_HOMEa pasta de dados da plataformamove o livro-razão, para manter experimentos longe das contas reais
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

Arquitetura

trayvvaultledgeracctacctacctclaudecodexgrok
A bandeja e a CLI compartilham um store, que guarda um armário privado por conta e inicia cada harness a partir do seu.

crates/core guarda todo o comportamento. A CLI e o backend do Tauri são front ends finos sobre o mesmo Store e as mesmas funções, então o app de bandeja e o vvault sempre concordam.

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 ou ApiKey), Account, Config, Provider.
  • launch.rs: monta o Launch (programa, args, env) e limpa o ambiente herdado.
  • limits.rs, status.rs, balance.rs, claude.rs, codex.rs: leem limites, estado de sessão e saldos por harness.
  • kit.rs: liga instruções compartilhadas aos perfis. machine.rs: a conta padrão da máquina inteira.
  • terminal.rs: abre uma janela de terminal que reentra por vvault run.

Abrindo uma conta

vvault runiddroppedhomekeychainat launchharness
As variáveis de identidade são descartadas numa comporta e a chave sai do keychain só no lançamento.
  1. 1EscolherVocê escolhe uma conta no app de bandeja ou roda vvault open. O terminal executa vvault run <id>, então a chave é resolvida dentro desse processo.
  2. 2Validarlaunch::plan chama Account::validate, e então ensure_home cria o diretório do perfil, privado para o usuário.
  3. 3LimparAs variáveis herdadas que sobrescrevem a identidade são removidas: 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 a chaveNuma conta com chave de API, a chave é lida do keychain do SO naquele momento e passada apenas pelo ambiente.
  5. 5LançarO harness inicia com a variável home da conta, os argumentos de modelo e as entradas do kit ligadas ao perfil.

Por harness, uma chave de API chega como ANTHROPIC_API_KEY, ou ANTHROPIC_AUTH_TOKEN com --bearer, para o Claude; como VVAULT_API_KEY lida por um provider definido com flags -c para o Codex; e como XAI_API_KEY para o Grok. O Codex precisa de um endpoint que fale a Responses API.

Livro-razão e store

store::Store abre VVAULT_HOME ou o diretório de dados da plataforma (project dirs sh/versatile/vvault). A raiz é criada com modo 0700 e ledger.json é escrito com 0600.

  • Store::update pega um lock exclusivo em .lock, carrega o livro-razão, aplica sua closure, valida cada conta e provider, e então escreve por write_json.
  • write_json escreve um arquivo temporário privado no mesmo diretório, chama sync_all e o renomeia sobre ledger.json, então um crash nunca deixa um livro-razão pela metade.
  • Campos de uma conta: id (UUID), label (1 a 80 caracteres, sem caracteres de controle), harness, auth, model, fast_model, home, native_home, env, args, kit.
  • O home de uma conta gerenciada é profiles/<id>. Contas native_home usam a pasta do próprio harness, como o adopt faz, e nunca são copiadas.
  • Os caches ficam em arquivos por id como limits/<id>.json; o id precisa ser um UUID válido, o que bloqueia truques de caminho.
  • Os labels são únicos sem diferenciar maiúsculas, verificado de novo dentro do update com lock.

Limites e keep-alive

statususagebalancesession / weeklykeep-alive
As leituras de uso preenchem um livro-razão com medidores de sessão e semanais por conta, mantidos em dia por um relógio de keep-alive.
ContaFonteAtualidade
Login do Claude Codeendpoints de conta da Anthropic, mais os rate_limits que o Claude Code envia à sua status lineapós o login, depois no máximo uma vez por minuto
Login do Codexas requisições account/read e account/rateLimits/read da CLI do Codexapós o login, depois no máximo uma vez por minuto
Login do Groksó o estado da sessãonenhuma
Chaves OpenRouter, DeepSeeka requisição de chave ou saldo do providerno máximo a cada dois minutos
  • Os limites têm uma Window de sessão e uma semanal (percent 0 a 100, resets_at). settled zera qualquer janela cujo horário de reset já passou.
  • A status line é injetada com --settings no lançamento, então seu settings.json não é modificado. Uma status line existente continua rodando.
  • status.rs faz cache do estado de login e rechecagem após 50 minutos; keepalive renova contas ociosas pedindo a cada harness o próprio status.
  • No macOS o Claude Code guarda o login no Keychain, então lá os limites do Claude vêm só da status line.

Modelo de segurança

acct 1acct 2no copykeychainkeyhttp: refusedhttps
Um armário por conta, sem cópias, as chaves ficam no keychain e http puro é recusado.
RegraSignificado
Um home por contacredenciais nunca são copiadas entre pastas
O harness é dono dos seus tokenslogin, renovação e logout são feitos pelo harness
Chaves no keychain do SOmacOS Keychain, Windows Credential Manager ou Secret Service, sob o serviço vvault; nunca no livro-razão, num arquivo de configuração ou numa linha de comando
Chaves resolvidas no fimlidas dentro de vvault run e passadas por ambiente
Texto puro recusadoum endpoint customizado precisa ser https://, http:// puro só para localhost, 127.0.0.1 ou [::1]
Sem reuso de chaveum valor env extra que repita a chave de API é recusado

Uma exceção somente de leitura: para mostrar os limites do Claude e o nome do plano, o access token que o Claude Code salvou é lido em memória e enviado apenas aos endpoints de conta da Anthropic (api.anthropic.com/api/oauth/usage e /profile). Eles não são documentados; se mudarem, os limites recorrem à status line.

Decisões e limites

DecisãoEscolhidoRejeitadoPor quê
Tratamento de tokensnunca tocar nos tokens OAuthcopiá-los ou renová-losum refresh token que rotaciona deve viver em um só lugar
Isolamentouma pasta home por conta via CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOMEtrocar credenciais dentro de uma pastasem cópias, uma sessão
Padrão da máquinaapontar o harness para o home da contacopiar a conta para o home padrãonada é copiado; só contas de login, já que uma chave ficaria em todo shell
Entrega de chavesleitura do keychain no lançamento, só por ambienteguardar chaves no livro-razão ou em flagsas chaves ficam fora de arquivos e linhas de comando
Escritas do livro-razãocom lock, validadas, rename atômicosobrescrita simplesnenhum livro-razão pela metade ou inválido
UIHTML, CSS, JS purosum build de frontendsem etapa de build para o app de bandeja
  • Os limites do Grok não são informados: a CLI do Grok só expõe o estado da sessão.
  • As contas do Grok usam o endpoint da xAI; um endpoint customizado é recusado.
  • Os endpoints de uso e perfil da Anthropic não são documentados e podem mudar.
  • Terminais já abertos mantêm sua conta até você rodar eval "$(vvault env)" ou reabri-los.
  • Nenhum número de desempenho medido é publicado para este projeto.

Arquivos para ler