walletdocs

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.db

SQLite file (created + migrated automatically). Default: ./data/wallet.db

Example: WALLET_DB_PATH=./data/wallet.db

WALLET_CURRENCYdefault USD

Defaults for new users (each user can change their base currency in Settings).

Example: WALLET_CURRENCY=USD

WALLET_LOCALEdefault en-US

Defaults for new users (each user can change their base currency in Settings).

Example: WALLET_LOCALE=en-US

WALLET_TIMEZONEdefault the system time zone

Defaults for new users (each user can change their base currency in Settings).

Example: WALLET_TIMEZONE=America/New_York

WALLET_PUBLIC_URLdefault derived from the request

Public 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_URL

Passkey 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_TOKEN

Empty (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_HOSTS

Extra hostnames allowed for token-less access, e.g. a LAN name (comma-separated). Use with care.

WALLET_USER_IDdefault the owner

Which user the stdio MCP server, token-only API calls and the CLI tools act as (default: the owner).

WALLET_BACKGROUND_REFRESH

The 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_BACKUPS

A 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_DIR

A backup of the database every day (kept 14 days + 8 weekly), in WALLET_BACKUP_DIR (default: backups/ next to it).

WALLET_UPLOAD_DAYS

Uploaded statements are deleted after this many days.

Example: WALLET_UPLOAD_DAYS=90

Brokerage connections

WALLET_SECRET_KEY

Broker 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 anthropic

anthropic (Claude API, default) | claude-code (your local claude CLI) | codex (your local codex CLI) | none

Example: WALLET_AGENT_PROVIDER=anthropic

ANTHROPIC_API_KEY

For the anthropic provider (or run ant auth login)

WALLET_AGENT_MODELdefault claude-opus-5-5

For the anthropic provider (or run ant auth login)

Example: WALLET_AGENT_MODEL=claude-opus-5-5

WALLET_AGENT_EFFORTdefault medium

low | medium | high | xhigh | max

Example: WALLET_AGENT_EFFORT=medium

WALLET_AGENT_READONLYdefault 0

Set to 1 to hide every write tool (record_balance, import…) from all agents and MCP clients.

Example: WALLET_AGENT_READONLY=0

WALLET_CLAUDE_BINdefault claude

Optional overrides for the local CLI providers

Example: WALLET_CLAUDE_BIN=claude

WALLET_CLAUDE_MODEL

Optional overrides for the local CLI providers

WALLET_CODEX_BINdefault codex

Optional overrides for the local CLI providers

Example: WALLET_CODEX_BIN=codex

WALLET_CODEX_MODEL

Optional overrides for the local CLI providers

Telegram reminders (npm run worker)

TELEGRAM_BOT_TOKEN

Create a bot with @BotFather and paste its token. Each user links their chat from Settings → Telegram.

TELEGRAM_BOT_USERNAME

Optional: the bot's @username for one-tap "Open in Telegram" links (otherwise looked up with the token).

TELEGRAM_CHAT_ID

Optional 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.

PORT

Port 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_URL

Base URL of a self-hosted Telegram Bot API server for the worker (default https://api.telegram.org).

Read in src/bin/worker.ts

NEXT_RUNTIME

Undocumented.

Read in src/instrumentation.ts

ANTHROPIC_AUTH_TOKEN

Accepted instead of ANTHROPIC_API_KEY by the anthropic provider (bearer-token auth in the SDK).

Read in src/server/agent/providers/anthropic.ts

ANTHROPIC_PROFILE

Accepted instead of ANTHROPIC_API_KEY: a credentials profile from ant auth login (a ~/.config/anthropic directory also counts).

Read in src/server/agent/providers/anthropic.ts

WALLET_ROOT

Repository root the CLI providers use to find bin/wallet-mcp.mjs (default: the working directory).

Read in src/server/agent/providers/cli.ts

WALLET_MCP_COMMAND

Command the claude-code / codex providers run to start the wallet MCP server, split on spaces (default: node bin/wallet-mcp.mjs).

Read in src/server/agent/providers/cli.ts

WALLET_MIGRATIONS_DIR

Folder of drizzle migrations, tried before ./drizzle (it must contain meta/_journal.json).

Read in src/server/db/client.ts

Edit this page on GitHubReference generated from .env.example