All docs ▾
Getting started
Using Vex
Configuration
The config directory per OS, and every file in it.
Vex keeps the state it owns in one directory, referred to throughout the source as CONFIG_DIR: your encrypted keystores and vault, the plaintext settings file, the generated Docker Compose stack, keystore backups and the desktop app’s logs. The one deliberate exception is Vex Studio projects, which live in your home directory because they are folders you open in your own editor. Nothing in either place is uploaded anywhere.
Where it lives
| Platform | Path |
|---|---|
| Linux | ~/.config/vex |
| macOS | ~/Library/Application Support/vex |
| Windows | %APPDATA%\vex |
On Linux an absolute XDG_CONFIG_HOME is honoured in place of ~/.config, and on Windows an absolute %APPDATA% in place of the default. Set VEX_CONFIG_DIRto override the whole path. It must be absolute: a relative value is rejected rather than resolved against whatever the working directory happened to be, because a typo must never put privileged state in a launcher’s cwd. This is also the fix for running the app under WSL2, which launches the Windows Electron binary and would otherwise use %APPDATA%\vex. See Environment variables.
The same resolver is implemented three times over, in the app, in the agent runtime and independently in the Go bridge, and all three are run against one set of golden vectors. They have to agree: the Studio socket’s name is derived from this directory, so a drift would be a bridge dialling a path the app never bound.
What’s inside
| Entry | What it holds |
|---|---|
.env | Non-secret configuration: AGENT_MODEL, AGENT_PROVIDER and the four EMBEDDING_* keys. Secrets are actively stripped out of this file when the vault is written. |
secrets.vault.json | The encrypted secret vault: your API keys, sealed with AES-256-GCM under a scrypt-derived master key. Never contains plaintext. |
.install-id | The per-install UUID that names your Docker Compose project. |
.setup-complete | Marker written when the first-run wizard finishes; its absence sends you back through setup. |
keystore.json | Your EVM wallet keystore, encrypted. Wallets added later get their own wallet-<id>.json beside it. |
solana-keystore.json | The same, for the Solana key family. |
config.json | Plaintext settings: wallet inventory (addresses only, never secrets), chain configuration, service URLs, RPC overrides and projectsRoot. |
compose/ | The docker-compose.yml Vex renders for your install: Postgres with pgvector, plus the local embeddings runtime. |
local-infra/secrets/pg_password | The generated Postgres password, passed to the container as a file secret rather than an environment variable. |
backups/ | One timestamped folder per backup, each holding your keystores, the encrypted vault, .env, config.json and a manifest. The 20 most recent are kept. The key material inside stays encrypted; a backup is not a plaintext key. |
.electron-state/ | Desktop app state and logs; the main-process log is at .electron-state/logs/main.log. |
keystore.json, the per-wallet keystores, solana-keystore.json, secrets.vault.json and backups/ are the only copies of your keys that exist anywhere. Deleting this directory is irreversible. Export your keystores before you move, reinstall or clean up. See Troubleshooting.
Inside config.json
config.json is deliberately plaintext and deliberately boring: it holds the things that are not secrets, so you can read and edit them without unlocking anything.
- Wallet inventory: addresses and labels for the wallets you generated or imported, in two families, EVM and Solana. Private material stays in the keystore files.
- Chain configuration and service URLs: the default EVM chain (id, name, RPC and explorer, Ethereum mainnet out of the box), the Solana cluster and its RPC, and the endpoint each protocol client talks to.
- RPC overrides:
localChainRpcUrlsandpendleRpcUrls, both keyed by chain id as a string, let you point Vex at your own nodes instead of the defaults. projectsRoot: where Vex Studio projects live, default~/Vex/projects. Absolute paths only; a relative value is ignored with a warning. Once projects exist the recorded root is proved unchanged on every read and write, so changing this afterwards is refused rather than silently re-homing them. See Vex Studio.
Logs
When something goes wrong, the main-process log is the first place to look. It is inside the same config directory:
# Linux ~/.config/vex/.electron-state/logs/main.log # macOS ~/Library/Application\ Support/vex/.electron-state/logs/main.log # Windows %APPDATA%\vex\.electron-state\logs\main.log
The app logs through a redacting wrapper rather than the raw logger, including its uncaught-error handler, so values are scrubbed on the way to the file. The in-app “Report an issue” dialog is a separate, local-first path: the main process redacts what you typed and stores the report in your own database. No log file is attached to it, and this build ships no upload transport, so the report stays on your machine. What Vex does and does not send is covered in Privacy.