Overview
Getting started
Install wallet, explore it with demo data, create your account with a passkey, and run it with Docker.
Requirements
- Node.js 22 or newer (
engines.nodeis>=22).better-sqlite3ships prebuilt binaries for common platforms; elsewherenpm installcompiles it, which needs Python,makeand a C++ compiler. - A browser with passkeys: Safari, Chrome, Edge or Firefox, with Touch ID, Face ID, Windows Hello, a password manager or a phone.
- Optional: an Anthropic API key (or a logged-in
claude/codexCLI) for the assistant, and a Telegram bot token for reminders.
Install and run
git clone https://github.com/Clanker-Labs/wallet.git
cd wallet
npm install
npm run dev # http://localhost:3000The database is created and migrated on first use at ./data/wallet.db (set WALLET_DB_PATH to move it). Open http://localhost:3000: with no users yet you land on Set up your wallet.
Try it with demo data
The fastest way to see every feature is the demo profile, "Alex": two years of history, USD and EUR accounts, a US brokerage and 401(k), a French PEA, crypto, gold coins, a flat with a mortgage, budgets, reminders and saved simulations. It also stores synthetic exchange rates and prices, so it works offline.
npm run db:seed-demo # adds the demo data to the owner (creates "Alex" if there is no user yet)
npm run auth:link # prints a one-time sign-in link, valid 15 minutesOpen the printed link (http://localhost:3000/api/auth/magic?code=…). It signs you in and takes you to Settings → Security, where you add a passkey so you can sign in normally next time.
db:seed-demo refuses to touch an owner who already has accounts; pass -- --force to add the demo data anyway. npm run auth:link -- --list lists users and -- --user <id> mints a link for someone else.
Create your own account
On a fresh database, /signup asks for your name and creates a passkey:
- Create my passkey uses this device: Touch ID, Face ID, Windows Hello or your password manager.
- Save it on my iPhone (QR code) shows a QR code on the computer. Scan it with the iPhone camera, confirm with Face ID, and the passkey is stored in iCloud Keychain. Next time, sign in the same way: one tap, or one scan.
The first account is the owner. Anyone else can create their own separate wallet at /signup; set WALLET_ALLOW_SIGNUP=0 to close sign-ups (see Sign-up). Add more passkeys (a laptop, a security key) in Settings → Security.
Then, in order:
- Settings → Preferences: pick your base currency (USD by default), locale and time zone.
- Accounts: add each bank account, savings account, brokerage, property and loan in its own currency (Accounts).
- Investments: add positions by symbol; prices are fetched for you (Investments).
- Transactions: import a CSV export, or drop a statement on the assistant (Transactions).
- Budgets and Reminders when you're ready.
Configure the assistant and Telegram
cp .env.example .env- Assistant: set
ANTHROPIC_API_KEY(or runant auth login), or use a local CLI login withWALLET_AGENT_PROVIDER=claude-codeorcodex. See Assistant. - Telegram: create a bot with @BotFather, set
TELEGRAM_BOT_TOKEN, runnpm run worker, then link your chat in Settings → Telegram. See Reminders & Telegram.
Every variable is listed in Configuration.
Run it for real
With Docker:
cp .env.example .env # set WALLET_PUBLIC_URL, and WALLET_API_TOKEN if the port is reachable from a network
docker compose up -d # web on 127.0.0.1:3000 (loopback only)
docker compose --profile telegram up -d # add the Telegram / prices / FX workerWALLET_PORT changes the host port and WALLET_DATA binds the database to a host directory; see Deployment.
Without Docker:
npm run build && npm start # the web app
npm run worker # Telegram bot, reminders, hourly FX rates and pricesKeep both running (systemd, pm2, launchd…). The worker is only needed for Telegram and reminders. Exchange rates, prices and investment snapshots are also refreshed by the web app in the background while you use it. Put it behind HTTPS before using it from other devices; Deployment covers reverse proxies, WALLET_PUBLIC_URL and backups.