All docs ▾
Getting started
Using Vex
Environment variables
Every variable the app and the bridge read.
Most people never touch these. The setup wizard writes the non-secret ones into .env inside your config directory, and stores the secret ones in the encrypted vault instead. This page is the reference for when you want to run Vex against your own infrastructure, or need to know exactly what the app and the vex-mcp bridge read at runtime.
API keys belong in the vault, not in a shell profile. The wizard puts them there, and the app mirrors them into the engine’s process environment only after you unlock. They are never written to .env in plaintext, and the writer strips them from that file if they are found there.
Inference and research keys
| Variable | Purpose |
|---|---|
OPENROUTER_API_KEY | Required. Inference runs on your own OpenRouter account and your own budget; without it, and without AGENT_MODEL, the agent and every background worker stay idle. |
AGENT_MODEL | The model id the agent runs on: any OpenRouter model id. Chosen in the wizard, changeable later, stored in .env. |
AGENT_PROVIDER | The inference provider. Optional and auto-detected; openrouter is the only valid value, and anything else fails validation at startup. |
OPENROUTER_ENDPOINT_TAG | Optional. Pins OpenRouter routing to one endpoint tag; unset means Auto. |
JUPITER_API_KEY | Needed by every Solana tool in the catalog: swaps, prices, token search, Jupiter Lend and the prediction surface. Optional if you only work on EVM chains. |
TAVILY_API_KEY | Optional. Enables the WebResearch tool, which is hidden from the model without it, and is one of the sources the market-regime worker gates on. |
RETTIWT_API_KEY | Optional. Enables the TwitterAccount tool, and the regime worker’s second source. |
RELAY_API_KEY | Optional. Relay bridging works fully without it; a key only raises Relay’s rate limits. |
Three optional numbers tune the agent itself: AGENT_CONTEXT_LIMIT (1,000 to 2,000,000 tokens, default 256,000), AGENT_MAX_OUTPUT_TOKENS (256 to 128,000, default 16,384) and AGENT_TEMPERATURE (0 to 2, provider default when unset). A value outside its range is rejected at startup rather than clamped.
Secrets and paths
| Variable | Purpose |
|---|---|
VEX_KEYSTORE_PASSWORD | Your master password, for automation flows. On unlock the app deletes it from the process environment and holds the password in memory instead, and it is never written to disk. |
VEX_CONFIG_DIR | Overrides the per-OS config directory. Must be an absolute path: a relative value is ignored, not resolved. Read by the app, the agent runtime and the bridge, which all derive the same directory. |
VEX_PROJECT_ID | Read by the vex-mcp bridge to pick a Studio project, equivalent to passing --project <uuid>. It must be a UUID. |
VEX_STUDIO_SOCKET | Overrides the derived Studio endpoint path. Validated before the host binds, and a value that fails validation refuses startup by name rather than silently falling back to the derived path. |
Local stack and embeddings
The Docker stack Vex renders publishes Postgres on 127.0.0.1:27432 and the embeddings runtime on 127.0.0.1:27134, both on the loopback interface only. Those ports are substituted into the compose file when it is rendered, so they are literal values in the generated docker-compose.yml rather than variables your shell can override.
The four EMBEDDING_* keys are all required, and the wizard writes all four into .env on first run:
| Variable | Default written | Purpose |
|---|---|---|
EMBEDDING_BASE_URL | http://127.0.0.1:27134/v1 | Where the embeddings runtime is reachable. The client appends /embeddings. Always 127.0.0.1, never localhost, so the probe and the engine cannot disagree over IPv6. |
EMBEDDING_MODEL | ai/embeddinggemma:300M-Q8_0 | The model id sent with every request. |
EMBEDDING_DIM | 768 | Vector dimension, 1 to 8192. It must match what the model actually returns; the value is stamped on every stored row and recall filters on it. |
EMBEDDING_PROVIDER | local | A tag for logging and observability. |
Changing the embedding model or dimension is not a plain edit: existing vectors were produced by the old model. The export and re-embed procedure is in Troubleshooting, and what is stored is described in Memory.
Diagnostics and updates
| Variable | Purpose |
|---|---|
VEX_SENTRY_DSN | Crash-reporting endpoint. Reporting is strictly opt-in; with no DSN present the consent control is hidden entirely. |
VEX_UPDATER_DEV_FEED | Set to exactly 1 in an unpackaged development build to point the auto-updater at a local feed. Ignored in a packaged app; leave it unset. |
What crash reports contain, and what is scrubbed before sending, is covered in Privacy.