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.
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 caminho | Papel |
|---|---|
| crates/core | livro-razão, launcher, keychain, limites, keep-alive |
| crates/cli | o comando vvault |
| app/src-tauri | backend do app de bandeja |
| app/ui | interface 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.
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-protocolCom um livro-razão novo, 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| Variável | Padrão | Efeito |
|---|---|---|
| VVAULT_HOME | a pasta de dados da plataforma | move o livro-razão, para manter experimentos longe das contas reais |
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-devArquitetura
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.
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
- 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.
- 2Validarlaunch::plan chama Account::validate, e então ensure_home cria o diretório do perfil, privado para o usuário.
- 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.
- 4Resolver a chaveNuma conta com chave de API, a chave é lida do keychain do SO naquele momento e passada apenas pelo ambiente.
- 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
| Conta | Fonte | Atualidade |
|---|---|---|
| Login do Claude Code | endpoints de conta da Anthropic, mais os rate_limits que o Claude Code envia à sua status line | após o login, depois no máximo uma vez por minuto |
| Login do Codex | as requisições account/read e account/rateLimits/read da CLI do Codex | após o login, depois no máximo uma vez por minuto |
| Login do Grok | só o estado da sessão | nenhuma |
| Chaves OpenRouter, DeepSeek | a requisição de chave ou saldo do provider | no 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
| Regra | Significado |
|---|---|
| Um home por conta | credenciais nunca são copiadas entre pastas |
| O harness é dono dos seus tokens | login, renovação e logout são feitos pelo harness |
| Chaves no keychain do SO | macOS 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 fim | lidas dentro de vvault run e passadas por ambiente |
| Texto puro recusado | um endpoint customizado precisa ser https://, http:// puro só para localhost, 127.0.0.1 ou [::1] |
| Sem reuso de chave | um 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ão | Escolhido | Rejeitado | Por quê |
|---|---|---|---|
| Tratamento de tokens | nunca tocar nos tokens OAuth | copiá-los ou renová-los | um refresh token que rotaciona deve viver em um só lugar |
| Isolamento | uma pasta home por conta via CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME | trocar credenciais dentro de uma pasta | sem cópias, uma sessão |
| Padrão da máquina | apontar o harness para o home da conta | copiar a conta para o home padrão | nada é copiado; só contas de login, já que uma chave ficaria em todo shell |
| Entrega de chaves | leitura do keychain no lançamento, só por ambiente | guardar chaves no livro-razão ou em flags | as chaves ficam fora de arquivos e linhas de comando |
| Escritas do livro-razão | com lock, validadas, rename atômico | sobrescrita simples | nenhum livro-razão pela metade ou inválido |
| UI | HTML, CSS, JS puros | um build de frontend | sem 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
- README.mdinstalação, uso, configuração, estrutura
- docs/usage.mdpadrões, providers, kit, limites, modelos, keep-alive
- docs/safety.mdas regras de segurança completas
- crates/core/src/model.rsHarness, Auth, Account e validação
- crates/core/src/store.rsraiz do livro-razão, locking, escritas atômicas
- crates/core/src/launch.rslimpeza do ambiente e plano de lançamento por harness
- crates/core/src/secrets.rsacesso ao keychain
- crates/core/src/limits.rsjanelas de limite e throttling de sondagens
- crates/core/src/status.rsestado da sessão e keep-alive
- crates/core/src/machine.rsconta padrão da máquina inteira
- crates/cli/src/main.rsa superfície do comando vvault
- app/src-tauri/src/main.rscomandos do app de bandeja