Security Model: vault.json vs OS Keychain, AES-GCM Backups & Network Endpoints
Exact security guarantees of agy-swap: plaintext 0600 vault.json default, opt-in AGY_SWAP_VAULT=keychain, AES-GCM backups, SHA-256/512 verification, and exact network endpoints.
How Saved Tokens and Active Sessions Are Stored
We state storage details directly without vague claims:
Saved account tokens live in vault.json (permissions 0600) inside your agy-swap configuration directory. That file is not encrypted.
Set AGY_SWAP_VAULT=keychain to store saved tokens in macOS Keychain (native Security.framework), Windows Credential Manager, or Linux Secret Service instead, or AGY_SWAP_VAULT=file to force file storage.
If a selected vault cannot be written, agy-swap retains token_data in accounts.json (0600) and flags vault_migration in agy-swap doctor until you run agy-swap account migrate --force.
Active session switching writes OAuth credentials to ~/.gemini (0600) and mirrors the active session into the system keychain (/usr/bin/security on macOS or secret-tool on Linux when installed).
Metadata exports omit secrets. Secret exports (agy-swap backup export --include-secrets) encrypt payloads using AES-GCM with PBKDF2-HMAC-SHA256 (600,000 iterations) and maintain an import recovery journal.
All config updates acquire advisory file locks (flock on Unix, LockFileEx on Windows) and rename temporary files atomically. Tokens are redacted from logs and CLI output.
install.sh and install.ps1 verify release binaries against SHA-256 checksums.txt; agy-swap install-agy verifies the official Google Antigravity CLI download against SHA-512 checksums.
Fallback latest-version lookup during agy-swap update when GitHub is unreachable
DNS-over-HTTPS (1.1.1.1, 8.8.8.8, or AGY_SWAP_DOH_URL)
Host lookup retry strictly after a TLS verification/connection error
Custom mirror / Go proxy / Google CLI download
Only when AGY_SWAP_RELEASE_MIRROR, Go fallback, or install-agy is explicitly used
Frequently Asked Questions
Does agy-swap send usage analytics, telemetry, or crash reports?
No. The binary sends zero telemetry and contacts no external analytics server.
Why is vault.json 0600 instead of encrypted by default?
Headless terminals and background --sync-session hooks cannot prompt for a master passphrase non-interactively. Storing tokens in user-only 0600 files keeps non-interactive automation working while AGY_SWAP_VAULT=keychain gives desktop users OS keyring storage.
How can I migrate from vault.json to OS Keychain?
Export AGY_SWAP_VAULT=keychain in your shell profile, run agy-swap account migrate, and run agy-swap doctor to confirm.
Try agy-swap in your terminal
Install with Homebrew, shell, PowerShell, or Go source, then save your accounts and inspect live quotas locally.