First run

The first launch does two things: it stands up the local data plane in Docker, then walks you through a seven-step wizard that creates your vault, your wallets and your model provider. Budget extra time here, because the one-time model download is part of it. Have your OpenRouter key ready. See Requirements.

What happens on boot

Before the wizard appears, the app moves through a fixed sequence: the cold-open gate, a system check, Docker bootstrap, Compose bootstrap and then database migrations with streamed progress. The main process renders a Compose file for this install and brings up Postgres with pgvector plus the local embeddings runtime, both published on 127.0.0.1, then applies the schema migrations. Anything that does not go cleanly hands off to the screen that owns the fix rather than dead-ending.

The setup wizard

1. Keystore

   Choose a master password, at least 10 characters. It derives the key that seals the encrypted vault with AES-256-GCM and scrypt N=2¹⁷, and it is held in memory only: it is never written to disk, not even to the config .env. There is no recovery path, so if you lose it, the vault and keystores are gone. See Keys & encryption.

2. Wallets

   Generate or import your EVM and Solana wallets. Keys are created on your machine and written to per-wallet encrypted keystore files; only ids, addresses and labels land in the plaintext config. More in Wallets & custody.

3. API keys

   Optional and skippable: Jupiter (needed to swap on Solana), Tavily (web research) and Rettiwt (X/Twitter research). Nothing here blocks the wizard; you get a warning and can continue. Anything you enter goes into the encrypted vault, and you can add these later in Settings.

4. Embedding

   Confirm the local embedding endpoint and dimension (768 by default) and let the wizard probe the runtime. This is what powers tool discovery and memory. The dimension is not freely changeable later: existing vectors pin it.

5. Agent core

   Optional agent tuning (context limit, max output tokens, temperature), written to the non-secret .env in your config directory. Leave a field empty to keep its current value. See Configuration.

6. Provider

   Enter your OpenRouter API key and pick the model (AGENT_MODEL) the agent runs on. The key is verified with a live call before it is stored in the encrypted vault; the model id is not a secret and goes to .env. Inference is billed to your own account.

7. Review

   Confirm and finalize. This screen carries the opt-in telemetry consent checkbox for crash reporting; leave it unchecked and nothing is sent. If the build has no telemetry endpoint configured, the card says so and there is nothing to consent to. See Privacy.

Unlocking after that

Every later launch stops at the unlock screen. Your master password decrypts the vault and its secrets are mirrored into the engine’s environment in memory, which is what lets the background workers do real work instead of no-ops. The same unlock starts the Vex Studio MCP listener, which is why Vex Studio needs Vex open and unlocked.

Wrong passwords are throttled from the first miss: roughly 1, 2, 4 and 8 seconds, then 30 seconds from the fifth failure and 5 minutes from the tenth. Only a genuinely wrong password advances that counter. The vault envelope is validated before any decryption runs, so a corrupted file reports as corruption rather than masquerading as a wrong password, and a successful unlock resets the backoff.

Where to go next

• Agent sessions: your first conversation and how tools get discovered.
• Approvals & the Safety Contract: what the approval cards mean before you sign anything.
• Fees: the 25 bps fee and when it never applies.