All docs ▾
Getting started
Using Vex
Environment variables
Provider keys, local paths, embeddings and Kairos runtime controls.
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.
Kairos runtime controls
These optional, non-secret settings tune response deadlines, independent reads, mission wakes and background work. Leaving a setting unset or blank uses the defaults below. Numeric settings in this section accept integers only; invalid or out-of-range values fail startup validation. The values are verified against Kairos’s shared configuration.
Model response deadlines
These limits apply to one model inference round, not to a tool dispatch. Each accepts 0–3,600,000 milliseconds; 0 disables that particular bound. The total deadline includes provider retries, endpoint failover backoff and buffered fallback.
| Variable | Default | What it limits |
|---|---|---|
AGENT_FIRST_CHUNK_TIMEOUT_MS | 90,000 ms | Time from the start of a request to its first chunk of any type. |
AGENT_STREAM_IDLE_TIMEOUT_MS | 60,000 ms | The longest silent gap between chunks after the first. |
AGENT_REASONING_ONLY_TIMEOUT_MS | 150,000 ms | Time from the first reasoning chunk to the first content or tool-call delta. |
AGENT_INFERENCE_ROUND_DEADLINE_MS | 300,000 ms | Total wall-clock time for one inference round. |
Independent reads and mission wakes
Tool concurrency and read deadlines apply only to audited, parallel-safe reads. They do not parallelize signing or submission, or time out a mutating tool. Mission wakes retain exclusion for the same session or selected wallet even when concurrency is raised.
| Variable | Default | Allowed values and behavior |
|---|---|---|
AGENT_TOOL_READ_CONCURRENCY | 3 | 1–8 independent, allowlisted tool reads at once. 1 runs them serially. |
AGENT_TOOL_READ_TIMEOUT_MS | 45,000 ms | 0–600,000 ms per allowlisted read. 0 disables the deadline. |
AGENT_TOOL_READ_EXTENDED_TIMEOUT_MS | 120,000 ms | 0–600,000 ms for allowlisted reads that legitimately take longer, including web research and multi-chain wallet scans. 0 disables the deadline. |
AGENT_WAKE_CONCURRENCY | 1 | 1–4 wake slices at once. The default runs one slice at a time. |
AGENT_WALLET_READ_PARALLEL | 1 | 0 or 1. 1 runs independent wallet balance and pricing legs concurrently; 0 runs them in their previous serial order. Provider-specific caps still apply. |
AGENT_WALLET_READ_LEG_TIMEOUT_MS | 25,000 ms | 0–120,000 ms per wallet-read leg. 0 disables the deadline. A missing answer stays unknown and makes totals partial; it never becomes a zero balance. |
Background reasoning
| Variable | Default | Purpose |
|---|---|---|
AUX_REASONING_EFFORT | lowest | Reasoning effort for compaction summaries and chunking, the memory judge, entity extraction and the market-regime worker. This is separate from chat preferences and accepted mission effort. |
Accepted values are lowest, provider, none, minimal, low, medium, high, xhigh and max, case-insensitive. lowest uses the lowest effort the model accepts, or low when its supported set is unknown. provider sends no effort override. An explicit effort is clamped down to what the model supports; an unrecognized value fails startup validation.
Database bounds
These settings bound waits in the engine’s PostgreSQL pools. All values are positive; 0 does not disable a database bound. The reserved control pool keeps capacity for Stop, lease renewal or release, and reconciliation.
| Variable | Default | Allowed values and purpose |
|---|---|---|
AGENT_DB_STATEMENT_TIMEOUT_MS | 30,000 ms | 1,000–3,600,000 ms. Server-side limit for one statement on the engine pools. |
AGENT_DB_CONNECTION_TIMEOUT_MS | 10,000 ms | 1,000–300,000 ms. Limit on waiting for a pooled connection. |
AGENT_DB_IDLE_IN_TRANSACTION_TIMEOUT_MS | 60,000 ms | 1,000–3,600,000 ms. Ends a database session left idle inside an open transaction. |
AGENT_DB_LONG_STATEMENT_TIMEOUT_MS | 300,000 ms | 1,000–3,600,000 ms. Raised per-transaction limit for known long statements, such as migrations and compaction commits. |
AGENT_DB_CONTROL_POOL_MAX | 2 | 1–5 connections reserved for control work. This is a connection count, not a timeout. |
Read projection and desk approval dispatch
| Variable | Default | Purpose |
|---|---|---|
AGENT_READ_PROJECTION | 0 (off) | 0 or 1. Optional projection of large DexScreener read answers for model-facing text. It removes values restated elsewhere in the same answer without dropping or rewriting money-critical values. Disabled by default. |
APPROVAL_DISPATCH_BACKGROUND | 1 (on) | 0 or 1. On the desk lane, acknowledges approval after the dispatch slot commits, then continues execution and settlement in the background and reports the outcome by event. 0 restores the previous awaited approval behavior. |
A responsive approval button confirms that Vex accepted an action for processing; execution success still depends on its verified outcome. These switches keep the same ownership, approval and signing checks. See turn progress and mission wakes for the behavior in the app.
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.