All docs ▾
Getting started
Using Vex
Keys & encryption
AES-256-GCM keystores, the scrypt-derived master key, unlock throttling.
Everything secret in Vex is protected by one thing you supply: the master password you set in the first-run wizard. From it the app derives the key that opens the secret vault, and with it the app opens the per-wallet keystores that hold your private keys. Nothing secret is written to disk unencrypted, and the password itself is never written at all.
The secret vault
API keys live in an encrypted vault file, secrets.vault.json, inside your config directory (see where that is per OS).
| Property | Value |
|---|---|
| File | secrets.vault.json in CONFIG_DIR |
| Key derivation | scrypt with N = 217, r = 8, p = 1, 32-byte key. That is the OWASP recommendation for password storage: a ~128 MiB working set and roughly 400 ms per unlock |
| Cipher | AES-256-GCM, with a random 16-byte salt and 12-byte IV per write |
| Master password | Held in memory only for the life of the process. It is never persisted, and setup strips any managed secret left in the plaintext .env |
| Bad-attempt handling | Backoff from the first wrong password: about 1, 2, 4 and 8 seconds, then 30 seconds from the fifth failure and 5 minutes from the tenth |
| Integrity | The envelope and the KDF parameters are validated before any decryption runs, so a corrupted or tampered file reports as corrupt rather than as a wrong password |
That ~400 ms is intentional. It is barely noticeable once per session, and it is what makes offline guessing against a stolen vault file expensive. Older vault files keep their own recorded parameters so they still open, and are rewritten to the current ones on the next successful unlock.
What the vault stores
The vault holds the provider and data-source credentials the agent needs. Non-secret settings live beside it in a plain .env; secrets never do.
| Key | Used for |
|---|---|
OPENROUTER_API_KEY | Inference. Required: the OpenRouter provider refuses to build without it |
JUPITER_API_KEY | Solana swaps |
TAVILY_API_KEY | Web research |
RETTIWT_API_KEY | X/Twitter research |
RELAY_API_KEY | Relay bridging. Optional, rate limits only |
On unlock, these are mirrored into the engine’s process environment so tools can use them, and they are read back from the encrypted vault on every start. See Environment variables.
Wallet keystores
Wallets are generated (or imported) on your machine and sealed into per-wallet keystore files: keystore.json for the original EVM wallet, solana-keystore.json for the original Solana one, and wallet-<id>.json for each additional wallet. Each file is AES-256-GCM with the same scrypt parameters as the vault, and a keystore records the parameters it was written with so it still opens after a future bump.
The wallet inventory itself is separate and deliberately boring: config.json is plaintext and holds ids, addresses, labels and creation dates, never key material. The keystore path is derived from the entry id rather than stored. So the app can list your wallets and show balances without anything secret being readable.
Keystores are auto-backed-up into a backups/ directory with retention and a restore path. An archive carries every keystore file, the encrypted vault, a sanitized .env and config.json, so the key material inside it is still sealed under your master password wherever you copy it. Private-key export exists for the case where you want your key elsewhere: it re-asks for the password, backs off on wrong answers and relocks the session after five, and writes to the clipboard under a lease that clears it again. See Wallets & custody.
Unlocking
After the wizard, every launch lands on the Unlock screen. One password opens both the vault and the keystores, and the backoff above applies there. Until you unlock, the agent has no provider key, in-process signing fails closed, and the Vex Studio listener is not accepting. The security model covers why that last one matters.
There is no recovery path. Vex cannot reset your master password, and no one at Vex can decrypt your vault or keystores. Lose the password and the funds behind those keys are gone unless you exported them elsewhere. Read What Vex can’t protect before you fund a wallet.