Reference
Configuration
Every environment variable wallet reads, generated from .env.example at build time, plus the few the code reads that aren't listed there.
Copy .env.example to .env and uncomment what you need. Every process loads the same files: Next.js (npm run dev / start), the worker (npm run worker) and the stdio MCP launcher (bin/wallet-mcp.mjs) read .env.local first, then .env, and real environment variables win over both. In Docker, docker-compose.yml passes .env to both containers and pins WALLET_DB_PATH=/data/wallet.db. Compose itself also reads WALLET_PORT (host port, default 3000) and WALLET_DATA (host directory for the database instead of the named volume); see Deployment.
Restart the processes after a change: nothing is reloaded at runtime. Per-user preferences (base currency, locale, time zone) live in the database and are edited in Settings; the WALLET_CURRENCY, WALLET_LOCALE and WALLET_TIMEZONE variables are only the defaults for users who haven't picked one.
Core
WALLET_DB_PATHdefault ./data/wallet.dbSQLite file (created + migrated automatically). Default: ./data/wallet.db
Example: WALLET_DB_PATH=./data/wallet.db
WALLET_CURRENCYdefault USDDefaults for new users (each user can change their base currency in Settings).
Example: WALLET_CURRENCY=USD
WALLET_LOCALEdefault en-USDefaults for new users (each user can change their base currency in Settings).
Example: WALLET_LOCALE=en-US
WALLET_TIMEZONEdefault the system time zoneDefaults for new users (each user can change their base currency in Settings).
Example: WALLET_TIMEZONE=America/New_York
WALLET_PUBLIC_URLdefault derived from the requestPublic URL of the web app. Used for passkeys behind a proxy, magic links and links in Telegram messages.
Example: WALLET_PUBLIC_URL=https://wallet.example.com
Accounts & passkeys
WALLET_ALLOW_SIGNUPdefault on (sign-ups open)Sign-in is passkey-only (Face ID / Touch ID / a phone via QR code). Passkeys need https, or http://localhost.
The first person to open the app creates the owner account. Anyone else can create their own (fully separate)
wallet at /signup. Set to 0 to close sign-ups once everyone's in (recommended if the app is reachable from the internet).
Example: WALLET_ALLOW_SIGNUP=1
WALLET_RP_IDdefault the host of WALLET_PUBLIC_URLPasskey relying-party id (defaults to the host of WALLET_PUBLIC_URL / the request).
Example: WALLET_RP_ID=wallet.example.com
Local API & MCP
WALLET_API_TOKENEmpty (default) = /api/* and /api/mcp need no token when called on localhost (and never from another
website in your browser). Such requests act as the owner (or WALLET_USER_ID).
Set a token as soon as the port is reachable from a network: openssl rand -hex 32
WALLET_ALLOWED_HOSTSExtra hostnames allowed for token-less access, e.g. a LAN name (comma-separated). Use with care.
WALLET_USER_IDdefault the ownerWhich user the stdio MCP server, token-only API calls and the CLI tools act as (default: the owner).
WALLET_BACKGROUND_REFRESHThe web server refreshes prices, rates, brokerage syncs and the daily snapshot of investment accounts
every hour by itself, so the daily net-worth chart has no gaps. Set to 0 to leave that to the worker.
Example: WALLET_BACKGROUND_REFRESH=1
WALLET_BACKUPSA backup of the database every day (kept 14 days + 8 weekly), in WALLET_BACKUP_DIR (default: backups/ next to it).
Example: WALLET_BACKUPS=1
WALLET_BACKUP_DIRA backup of the database every day (kept 14 days + 8 weekly), in WALLET_BACKUP_DIR (default: backups/ next to it).
WALLET_UPLOAD_DAYSUploaded statements are deleted after this many days.
Example: WALLET_UPLOAD_DAYS=90
Brokerage connections
WALLET_SECRET_KEYBroker API keys (Settings → Brokerage connections) are stored encrypted with this key.
Unset = a random key is generated once into secret.key next to the database (mode 0600).
Set it when the data directory is backed up somewhere you trust less than this machine.
Changing it makes stored broker keys unreadable: reconnect them afterwards.
Assistant
WALLET_AGENT_PROVIDERset in .env.exampledefault anthropicanthropic (Claude API, default) | claude-code (your local claude CLI) | codex (your local codex CLI) | none
Example: WALLET_AGENT_PROVIDER=anthropic
ANTHROPIC_API_KEYFor the anthropic provider (or run ant auth login)
WALLET_AGENT_MODELdefault claude-opus-5-5For the anthropic provider (or run ant auth login)
Example: WALLET_AGENT_MODEL=claude-opus-5-5
WALLET_AGENT_EFFORTdefault mediumlow | medium | high | xhigh | max
Example: WALLET_AGENT_EFFORT=medium
WALLET_AGENT_READONLYdefault 0Set to 1 to hide every write tool (record_balance, import…) from all agents and MCP clients.
Example: WALLET_AGENT_READONLY=0
WALLET_CLAUDE_BINdefault claudeOptional overrides for the local CLI providers
Example: WALLET_CLAUDE_BIN=claude
WALLET_CLAUDE_MODELOptional overrides for the local CLI providers
WALLET_CODEX_BINdefault codexOptional overrides for the local CLI providers
Example: WALLET_CODEX_BIN=codex
WALLET_CODEX_MODELOptional overrides for the local CLI providers
Telegram reminders (npm run worker)
TELEGRAM_BOT_TOKENCreate a bot with @BotFather and paste its token. Each user links their chat from Settings → Telegram.
TELEGRAM_BOT_USERNAMEOptional: the bot's @username for one-tap "Open in Telegram" links (otherwise looked up with the token).
TELEGRAM_CHAT_IDOptional legacy allowlist: these chat ids act as the owner without linking.
Also read by the code
Not in .env.example, found by scanning src/ and bin/ for process.env at build time.
PORTPort of next start (3000 in the Docker image). npm run auth:link also uses it to print http://localhost:$PORT/… when WALLET_PUBLIC_URL is unset.
Read in src/bin/login-link.ts
TELEGRAM_API_URLBase URL of a self-hosted Telegram Bot API server for the worker (default https://api.telegram.org).
Read in src/bin/worker.ts
ANTHROPIC_AUTH_TOKENAccepted instead of ANTHROPIC_API_KEY by the anthropic provider (bearer-token auth in the SDK).
ANTHROPIC_PROFILEAccepted instead of ANTHROPIC_API_KEY: a credentials profile from ant auth login (a ~/.config/anthropic directory also counts).
WALLET_ROOTRepository root the CLI providers use to find bin/wallet-mcp.mjs (default: the working directory).
WALLET_MCP_COMMANDCommand the claude-code / codex providers run to start the wallet MCP server, split on spaces (default: node bin/wallet-mcp.mjs).
WALLET_MIGRATIONS_DIRFolder of drizzle migrations, tried before ./drizzle (it must contain meta/_journal.json).
Read in src/server/db/client.ts