routstrd 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/Dockerfile DELETED
@@ -1,11 +0,0 @@
1
- FROM oven/bun:1-slim
2
- WORKDIR /app
3
-
4
- COPY package.json bun.lock ./
5
- RUN bun install --frozen-lockfile
6
-
7
- COPY . .
8
- RUN bun run build && bun install -g . && bun add -g @earendil-works/pi-coding-agent
9
-
10
- EXPOSE 8008
11
- CMD ["/bin/bash"]
package/IMPLEMENTATION.md DELETED
@@ -1,253 +0,0 @@
1
- # Migrate wallet storage from `~/.cocod` to `~/.routstrd/wallet`
2
-
3
- Task: [`routstrd-migrate-cocod-to-routstrd-files`](https://github.com/nodestrich/routstrd)
4
- Event ID: `2f420644005154c5b106017c4a753854bb2660ba834cde7e6e267532cb5448e9`
5
- Priority: 997 · Status: open
6
-
7
- ---
8
-
9
- ## Baseline
10
-
11
- This plan is based on `coco-integration` at `86ac688` (after the default-mint, NPC/npubx.cash, and Windows-support changes).
12
-
13
- The task branch is currently based on `04f8c22`; rebase it onto the latest `coco-integration` before implementing this plan.
14
-
15
- ## Goal
16
-
17
- Move the in-process Cashu wallet's persistent data from:
18
-
19
- ```text
20
- ~/.cocod/config.json
21
- ~/.cocod/coco.db
22
- ```
23
-
24
- to:
25
-
26
- ```text
27
- ~/.routstrd/wallet/config.json
28
- ~/.routstrd/wallet/coco.db
29
- ```
30
-
31
- The migration must preserve the mnemonic, proofs, default mint, and NPC identity. Existing users must not accidentally get a new wallet, and `cocod` and routstrd must never open the same database concurrently.
32
-
33
- Fresh installs must use `~/.routstrd/wallet` immediately. Existing installs must be migrated automatically and safely; merely continuing to run from `~/.cocod` is not sufficient for this task.
34
-
35
- ---
36
-
37
- ## Important corrections to the previous plan
38
-
39
- ### 1. Do not rename or migrate `cocod.sock`
40
-
41
- The in-process `coco-core` wallet does not expose a Unix socket. `cocod.sock` belongs to the legacy external `cocod` daemon and is used only to determine whether that daemon is still alive.
42
-
43
- There should therefore be no `wallet.sock`. Do not copy a socket inode into the new directory.
44
-
45
- ### 2. Keep legacy-process paths separate from wallet-data paths
46
-
47
- On the current base, `src/daemon/wallet/coco-client.ts` derives all of these from one `CONFIG_DIR`:
48
-
49
- - wallet config and database;
50
- - legacy cocod socket;
51
- - legacy cocod PID/process lock.
52
-
53
- That coupling must be removed. After migration:
54
-
55
- - wallet data comes from `~/.routstrd/wallet`;
56
- - probes and shutdown logic for an external legacy cocod continue to use `~/.cocod/cocod.sock` and `~/.cocod/cocod.pid`;
57
- - routstrd uses `~/.routstrd/wallet/wallet.pid` as the in-process wallet lock.
58
-
59
- While routstrd owns the migrated wallet, it should also retain the existing legacy-cocod exclusion mechanism (claiming the legacy `cocod.pid`) so an old cocod cannot be started against a stale or partially migrated legacy wallet. Acquisition and release of both locks must be rollback-safe.
60
-
61
- ### 3. Do not rename `cocodPath`
62
-
63
- `RoutstrdConfig.cocodPath` is an executable path for the external compatibility client, not a wallet storage path. Renaming it to `walletPath` would change its meaning and would not help this migration.
64
-
65
- The current daemon creates `createCocoClient()` directly and injects it into `createWalletAdapter()`, so `cocodPath` is effectively bypassed on the normal in-process path. Cleanup or removal of that compatibility setting is a separate task.
66
-
67
- ### 4. Do not implement fallback as the steady state
68
-
69
- A resolver that permanently falls back to `~/.cocod` does not move the data. Legacy detection is needed to initiate migration, but successful startup should resolve to the canonical directory afterward.
70
-
71
- ### 5. Account for the updated base
72
-
73
- The latest `coco-integration` adds:
74
-
75
- - `defaultMintUrl` persistence in the wallet's `config.json`;
76
- - the NPC plugin, whose Nostr identity is derived from the same mnemonic;
77
- - `src/daemon/wallet/coco-client.npc.test.ts`;
78
- - Windows support and `USERPROFILE` fallback.
79
-
80
- Migration must preserve the complete config JSON rather than reconstructing selected fields. Path construction must use `path.join` rather than hard-coded `/` separators.
81
-
82
- ---
83
-
84
- ## Current runtime path references on the latest base
85
-
86
- ### Wallet data and legacy process coordination
87
-
88
- | File | Current responsibility | Required change |
89
- |---|---|---|
90
- | `src/daemon/wallet/coco-client.ts` | Uses one `.cocod` directory for config, DB, socket, and PID; owns the in-process wallet and legacy-cocod guard | Split canonical data paths from legacy process paths; migrate before opening the DB; use `wallet.pid` for the in-process lock |
91
- | `src/daemon/wallet/cocod-client.ts` | External cocod compatibility client; defaults to `.cocod/cocod.sock` | Keep legacy defaults and clarify that they are external-cocod paths |
92
- | `src/cli.ts` | Initializes `.cocod`; two restart paths wait on `.cocod/cocod.pid` | Initialize/migrate the canonical wallet and wait on `wallet.pid` |
93
- | `src/utils/config.ts` | Defines `~/.routstrd`, but no wallet subdirectory | Export canonical and legacy wallet/process path helpers or constants |
94
- | `src/daemon/index.ts` | Calls `createCocoClient()` before building the adapter | Ensure migration occurs before the client opens the DB |
95
-
96
- ### Tests and documentation
97
-
98
- | File | Required update |
99
- |---|---|
100
- | `src/cli.test.ts` | Change fresh-wallet expectations and add migration coverage |
101
- | `src/daemon/wallet/coco-client.test.ts` | Update data/lock paths and add migration/dual-lock tests |
102
- | `src/daemon/wallet/coco-client.npc.test.ts` | Use the canonical wallet layout in fixtures; verify migrated mnemonic/config still drives NPC identity |
103
- | `README.md` | Document the new location and migration behavior; retain legacy cocod terminology only where discussing compatibility |
104
- | `SKILL.md` | Update wallet storage and environment-variable documentation |
105
-
106
- The fixture `src/daemon/wallet/fixtures/cocod-0.0.24-wallet.db.gz` keeps its name because it records the fixture's provenance.
107
-
108
- ---
109
-
110
- ## Target path model
111
-
112
- Define the path model in one dependency-light module (for example `src/daemon/wallet/paths.ts`, or in `src/utils/config.ts` if that does not introduce a cycle):
113
-
114
- ```text
115
- ROUTSTRD config root process.env.ROUTSTRD_DIR || ~/.routstrd
116
- canonical wallet directory process.env.ROUTSTRD_WALLET_DIR || <config root>/wallet
117
- canonical wallet config <wallet directory>/config.json
118
- canonical wallet database <wallet directory>/coco.db
119
- canonical wallet lock process.env.ROUTSTRD_WALLET_PID || <wallet directory>/wallet.pid
120
-
121
- legacy cocod directory process.env.COCOD_DIR || ~/.cocod
122
- legacy cocod socket process.env.COCOD_SOCKET || <legacy directory>/cocod.sock
123
- legacy cocod PID process.env.COCOD_PID || <legacy directory>/cocod.pid
124
- ```
125
-
126
- Use `HOME` with `USERPROFILE` fallback, matching the updated Windows-support base. Use functions or injectable path objects where tests need to change environment variables after module import.
127
-
128
- `COCOD_DIR`, `COCOD_SOCKET`, and `COCOD_PID` remain compatibility controls for locating an old external cocod. They must not redirect the new in-process wallet away from `~/.routstrd/wallet`. `ROUTSTRD_WALLET_DIR` is the new explicit data-directory override.
129
-
130
- ---
131
-
132
- ## Implementation plan
133
-
134
- ### Phase 1 — Centralize and separate paths
135
-
136
- 1. Add the canonical wallet and legacy cocod path definitions above.
137
- 2. Remove the local `.cocod` path construction from `coco-client.ts` and `cli.ts`.
138
- 3. Change `CreateCocoClientOptions` so tests/tooling can independently override:
139
- - wallet data directory;
140
- - wallet lock path;
141
- - legacy cocod socket and PID paths.
142
- 4. Keep `cocod-client.ts` pointed at the legacy socket. Do not make it import a resolver that prefers the new wallet directory.
143
-
144
- ### Phase 2 — Add a safe automatic migration primitive
145
-
146
- Add an idempotent `migrateLegacyWallet()` helper with injectable paths/filesystem operations for tests.
147
-
148
- Preconditions and behavior:
149
-
150
- 1. If the canonical wallet already contains both `config.json` and `coco.db`, return `already-current` and do not touch legacy data.
151
- 2. If neither canonical nor legacy wallet data exists, return `fresh`; initialization will create the canonical directory.
152
- 3. If only the legacy wallet exists:
153
- - first verify that legacy cocod is not running using the existing PID and socket guard;
154
- - create a private staging directory under `~/.routstrd` with mode `0700`;
155
- - copy the complete `config.json` and `coco.db` into staging without parsing or rewriting them;
156
- - apply `0600` to both files;
157
- - validate that the staged files exist and have the expected byte sizes;
158
- - atomically rename the staged directory to `wallet`;
159
- - only after the canonical directory is committed, remove the legacy `config.json` and `coco.db`;
160
- - never copy `cocod.sock` or `cocod.pid`.
161
- 4. If canonical storage is partial, legacy storage is partial, both contain wallet data, or files conflict, stop with an actionable error. Never merge databases and never generate a new mnemonic over an ambiguous state.
162
- 5. Clean up an uncommitted staging directory after failure. A committed canonical wallet remains authoritative if cleanup of the old files fails; report that cleanup warning clearly.
163
-
164
- The migration should preserve unknown config fields, including `defaultMintUrl`, and preserve the database byte-for-byte. This also preserves the NPC identity because that identity is derived from the mnemonic.
165
-
166
- A staging copy plus atomic directory rename is preferred over two independent file renames: a crash must not expose a half-created canonical wallet. Copying also permits a clear rollback before commit and supports a legacy directory located on another filesystem through `COCOD_DIR`.
167
-
168
- ### Phase 3 — Run migration from every wallet-opening path
169
-
170
- 1. **CLI onboarding/init:** run migration before `initializeWallet()`. Only initialize a new mnemonic when migration reports `fresh`.
171
- 2. **Daemon direct startup:** run migration before `createCocoClient()` opens `coco.db`. This covers users who invoke the daemon without rerunning onboarding.
172
- 3. **Start/restart/update/service paths:** retain `stopLegacyCocod()` before migration/startup where those paths already stop legacy cocod. Direct daemon startup should refuse with the existing actionable error rather than silently running two wallet engines.
173
- 4. Print a concise success message showing old and new directories, but never print config contents or the mnemonic during migration.
174
-
175
- A separate `routstrd wallet migrate` command is optional as a manual recovery/preview entry point, but it must call the same migration primitive. It is not a substitute for automatic migration.
176
-
177
- ### Phase 4 — Separate process locking
178
-
179
- Refactor the current `claimLegacyCocodPidFile()` behavior into explicit responsibilities:
180
-
181
- 1. Claim `wallet.pid` for the lifetime of the in-process wallet to prevent two routstrd wallet instances from opening `coco.db`.
182
- 2. Continue claiming the legacy `cocod.pid` while routstrd is active, after verifying no real cocod owns it, to prevent an old cocod from starting.
183
- 3. If either claim fails, release any claim already acquired before returning the error.
184
- 4. On `CocodClient.dispose()`, startup failure, and daemon shutdown, release only PID files still owned by the current process.
185
- 5. Keep `stopLegacyCocod()` and `assertLegacyCocodNotRunning()` operating only on legacy cocod paths.
186
- 6. Update both PID-release waits in `src/cli.ts` (`restartDaemonsAfterUpdate` and `restart`) to wait for the canonical `wallet.pid` rather than `.cocod/cocod.pid`.
187
-
188
- There is no canonical wallet socket.
189
-
190
- ### Phase 5 — Update initialization and client defaults
191
-
192
- 1. Make `initializeWallet()` default to the canonical wallet directory.
193
- 2. Preserve directory mode `0700` and config mode `0600` on both migrated and fresh wallets.
194
- 3. In `createCocoClient()`, derive `config.json` and `coco.db` from the canonical wallet directory, but take legacy guard paths separately.
195
- 4. Update the wallet-access comment near `unlock()` to reference `~/.routstrd/wallet/config.json`.
196
- 5. Leave `CocodClient`, `resolveCocodExecutable()`, and `cocodPath` compatibility behavior unchanged.
197
-
198
- ### Phase 6 — Tests
199
-
200
- Add or update tests for:
201
-
202
- - fresh initialization creates `~/.routstrd/wallet`, not `.cocod`;
203
- - a legacy config and database migrate byte-for-byte;
204
- - `defaultMintUrl` and unknown config fields survive migration;
205
- - the NPC-derived identity is unchanged after migration;
206
- - migration never copies socket or PID files;
207
- - migration refuses while a real legacy cocod is running;
208
- - stale legacy socket/PID handling remains safe;
209
- - an existing complete canonical wallet wins without modifying it;
210
- - partial canonical, partial legacy, and conflicting dual-wallet states fail without generating a mnemonic;
211
- - staging cleanup and retry after an interrupted migration;
212
- - custom `ROUTSTRD_DIR`, `ROUTSTRD_WALLET_DIR`, and legacy `COCOD_DIR` paths;
213
- - Windows-compatible path construction;
214
- - acquiring the second process lock rolls back the first on failure;
215
- - `dispose()` releases both owned locks and does not unlink another process's lock;
216
- - both CLI restart paths wait for `wallet.pid`.
217
-
218
- Keep `cocod-0.0.24-wallet.db.gz` unchanged and continue using it to prove the migrated database opens successfully with the current in-process wallet.
219
-
220
- ### Phase 7 — Documentation
221
-
222
- Update `README.md` and `SKILL.md` to state:
223
-
224
- - wallet data is stored in `~/.routstrd/wallet`;
225
- - existing `~/.cocod` data is migrated automatically on first startup;
226
- - users must back up the mnemonic before migration;
227
- - `ROUTSTRD_WALLET_DIR` overrides the canonical wallet directory;
228
- - `COCOD_DIR`, `COCOD_SOCKET`, `COCOD_PID`, and `cocodPath` refer only to legacy external-cocod compatibility.
229
-
230
- Do not replace every use of the word `cocod`: references to the external daemon, compatibility client, legacy guard, package, and fixture are still accurate.
231
-
232
- ---
233
-
234
- ## Acceptance criteria
235
-
236
- - A fresh install creates wallet data only under `~/.routstrd/wallet`.
237
- - Starting from a valid `.cocod` wallet results in the same config and database under the canonical directory without changing balances, mnemonic-derived NPC identity, or default mint.
238
- - No startup path silently creates a new mnemonic when recoverable legacy data exists.
239
- - A running legacy cocod blocks migration and database opening.
240
- - The new wallet directory contains no copied Unix socket and uses `wallet.pid` only as an in-process lock.
241
- - Legacy cocod probing and exclusion continue to use `.cocod/cocod.sock` and `.cocod/cocod.pid`.
242
- - The implementation works with `USERPROFILE`/Windows path construction and custom directory overrides.
243
- - All wallet, CLI, typecheck, and build tests pass on the rebased `coco-integration` branch.
244
-
245
- ---
246
-
247
- ## Suggested commit sequence
248
-
249
- 1. `refactor(wallet): separate routstrd wallet paths from legacy cocod paths`
250
- 2. `feat(wallet): atomically migrate legacy cocod wallet data`
251
- 3. `fix(wallet): use independent routstrd and legacy cocod process locks`
252
- 4. `test(wallet): cover migration, conflicts, NPC identity, and lock rollback`
253
- 5. `docs: document routstrd wallet storage and legacy migration`
package/SKILL.md DELETED
@@ -1,324 +0,0 @@
1
- # routstrd CLI Reference
2
-
3
- Routstr daemon — a Bun-based CLI tool that runs a background HTTP server for the Routstr protocol. It integrates with `cocod` for Cashu wallet management and routes LLM requests to available providers.
4
-
5
- ## Quick Start
6
-
7
- ```sh
8
- routstrd onboard # Initialize (creates config, sets up cocod)
9
- routstrd start # Start the daemon
10
- routstrd stop # Stop the daemon
11
- ```
12
-
13
- After onboarding, the daemon listens at `http://localhost:8008` and exposes an OpenAI-compatible API.
14
-
15
- ## Commands
16
-
17
- ### `routstrd onboard`
18
-
19
- Initialize routstrd for the first time:
20
- - Creates `~/.routstrd/` config directory
21
- - Creates `~/.routstrd/config.json` with defaults (port 8008, apikeys mode)
22
- - Installs `cocod` globally via bun if not present
23
- - Runs `cocod init` to set up the wallet
24
- - Starts the daemon and configures integrations
25
-
26
- ### `routstrd start`
27
-
28
- Start the background daemon process.
29
-
30
- | Option | Description |
31
- |--------|-------------|
32
- | `--port <port>` | Port to listen on (default: 8008) |
33
- | `-p, --provider <provider>` | Default provider to use |
34
-
35
- ### `routstrd stop`
36
-
37
- Stop the background daemon.
38
-
39
- ### `routstrd restart`
40
-
41
- Restart the daemon (stops if running, then starts).
42
-
43
- | Option | Description |
44
- |--------|-------------|
45
- | `--port <port>` | Port to listen on |
46
- | `-p, --provider <provider>` | Default provider to use |
47
-
48
- ### `routstrd status`
49
-
50
- Check daemon and wallet status. Returns JSON with current state.
51
-
52
- ### `routstrd balance`
53
-
54
- Get wallet and API key balances. Shows per-mint wallet balances, per-key API balances, and a grand total (all in sats).
55
-
56
- ### `routstrd models`
57
-
58
- List available routstr21 models (discovered via Nostr).
59
-
60
- | Option | Description |
61
- |--------|-------------|
62
- | `-r, --refresh` | Force refresh models from Nostr |
63
-
64
- ### `routstrd usage`
65
-
66
- Show recent usage logs and total sats cost.
67
-
68
- | Option | Default | Description |
69
- |--------|---------|-------------|
70
- | `-n, --limit <number>` | 10 | Number of recent entries (max 1000) |
71
-
72
- Shows timestamp, model, provider, sats cost, token counts, and request ID for each entry.
73
-
74
- ### `routstrd providers`
75
-
76
- List and manage providers (subcommand required).
77
-
78
- #### `routstrd providers list`
79
-
80
- List all providers with their enabled/disabled status. Shows index, status, and base URL.
81
-
82
- ```
83
- Providers (12 total, 2 disabled):
84
-
85
- [0] enabled https://provider1.example.com
86
- [1] enabled https://provider2.example.com
87
- [2] DISABLED https://provider3.example.com
88
- ```
89
-
90
- #### `routstrd providers disable <indices...>`
91
-
92
- Disable providers by their index numbers.
93
-
94
- ```sh
95
- routstrd providers disable 0 2 5
96
- ```
97
-
98
- #### `routstrd providers enable <indices...>`
99
-
100
- Enable providers by their index numbers.
101
-
102
- ```sh
103
- routstrd providers enable 0 2 5
104
- ```
105
-
106
- ### `routstrd clients`
107
-
108
- List and manage API clients (subcommand required).
109
-
110
- #### `routstrd clients list`
111
-
112
- List all registered clients with their ID, name, API key, and creation date.
113
-
114
-
115
- #### `routstrd clients add`
116
-
117
- Add a new client or set up a client integration.
118
-
119
- | Option | Description |
120
- |--------|-------------|
121
- | `-n, --name <name>` | Client name (required when not using integration flags) |
122
- | `--opencode` | Set up OpenCode integration |
123
- | `--openclaw` | Set up OpenClaw integration |
124
- | `--pi-agent` | Set up Pi Agent integration |
125
- | `--claude-code` | Set up Claude Code integration |
126
-
127
- ```sh
128
- routstrd clients add --opencode --pi-agent --claude-code # multiple integrations
129
- routstrd clients add -n "My App" # generic client
130
- ```
131
-
132
- Returns the client ID and API key for use with the OpenAI-compatible API.
133
-
134
- #### `routstrd clients delete <id>`
135
-
136
- Delete a registered client by its ID.
137
-
138
- ### `routstrd npubs`
139
-
140
-
141
- Manage admin npubs (subcommand required).
142
-
143
- | Command | Description |
144
- |---------|-------------|
145
- | `routstrd npubs list` | List configured admin npubs |
146
- | `routstrd npubs add <npub>` | Add an admin npub (accepts hex or npub1...) |
147
- | `routstrd npubs delete <npub>` | Delete an admin npub |
148
-
149
- ### `routstrd remote <url>`
150
-
151
- Configure a remote daemon URL. Generates a Nostr identity (nsec/npub) for NIP-98 authentication automatically.
152
-
153
- ```sh
154
- routstrd remote https://your-remote-daemon.com
155
- ```
156
-
157
- ### `routstrd refresh`
158
-
159
- Refresh routstr21 models from Nostr and re-run integrations for all registered clients.
160
-
161
- | Field | Type | Default | Description |
162
- |-------|------|---------|-------------|
163
- | `port` | number | 8008 | Daemon HTTP port |
164
- | `provider` | string\|null | null | Default provider URL |
165
- | `daemonUrl` | string\|null | null | Remote daemon URL |
166
- | `nsec` | string\|null | null | Nostr secret key for NIP-98 auth |
167
- | `cocodPath` | string\|null | null | Custom path to cocod executable |
168
- | `mode` | string | `"apikeys"` | Client mode (`apikeys` or `xcashu`) |
169
-
170
- | Variable | Default | Description |
171
- |----------|---------|-------------|
172
- | `ROUTSTRD_DIR` | `~/.routstrd` | Config directory |
173
- | `ROUTSTRD_WALLET_DIR` | `~/.routstrd/wallet` | In-process Cashu wallet data directory |
174
- | `ROUTSTRD_WALLET_PID` | `<wallet>/wallet.pid` | In-process wallet lock path |
175
- | `COCOD_DIR` | `~/.cocod` | Legacy external cocod compatibility directory |
176
-
177
- ### `routstrd mode`
178
-
179
- Interactive prompt to set the client mode:
180
- 1. **lazyrefund/apikeys** (default) — Pseudonymous accounts kept with Routstr nodes, refunded after 5 mins if unused.
181
- 2. **xcashu** (coming soon) — Balances never kept with nodes, all refunded in response.
182
-
183
- Changing mode restarts the daemon automatically.
184
-
185
- ### `routstrd monitor`
186
-
187
- Open an interactive TUI (htop-like) for usage monitoring.
188
-
189
- ### `routstrd logs`
190
-
191
- View daemon logs.
192
-
193
- | Option | Default | Description |
194
- |--------|---------|-------------|
195
- | `-f, --follow` | false | Follow log output (like `tail -f`) |
196
- | `-c, --coco` | false | Show Cashu wallet-engine (coco) logs instead of daemon logs |
197
- | `-n, --lines <number>` | 50 | Number of lines to show |
198
-
199
- Log files are stored at `~/.routstrd/logs/YYYY-MM-DD.log`. Wallet-engine (Cashu/coco) diagnostics go to a separate `~/.routstrd/coco-logs/YYYY-MM-DD.log` so they don't pollute the main daemon logs.
200
-
201
- ## Wallet Commands
202
-
203
- New wallets automatically trust `https://mint.cubabitcoin.org` as their default mint. The default is used when a wallet command does not include `--mint-url`.
204
-
205
- ### `routstrd wallet status`
206
-
207
- Check wallet status.
208
-
209
- ### `routstrd wallet unlock <passphrase>`
210
-
211
- Unlock the wallet with a passphrase.
212
-
213
- ### `routstrd wallet balance`
214
-
215
- Get wallet balance.
216
-
217
- ### `routstrd wallet receive cashu <token>`
218
-
219
- Receive funds via a Cashu token.
220
-
221
- ### `routstrd wallet receive bolt11 <amount>`
222
-
223
- Create a Lightning invoice to receive funds. Displays a QR code.
224
-
225
- | Option | Description |
226
- |--------|-------------|
227
- | `--mint-url <url>` | Mint URL to use |
228
-
229
- ### `routstrd wallet send cashu <amount>`
230
-
231
- Create a Cashu token to send.
232
-
233
- | Option | Description |
234
- |--------|-------------|
235
- | `--mint-url <url>` | Mint URL to use |
236
-
237
- ### `routstrd wallet send bolt11 <invoice>`
238
-
239
- Pay a Lightning invoice.
240
-
241
- | Option | Description |
242
- |--------|-------------|
243
- | `--mint-url <url>` | Mint URL to use |
244
-
245
- ### `routstrd wallet mints list`
246
-
247
- List configured wallet mints.
248
-
249
- ### `routstrd wallet mints add <url>`
250
-
251
- Add a new mint by URL.
252
-
253
- ### `routstrd wallet mints set-default <url>`
254
-
255
- Set the persistent default mint. If necessary, the mint is added as trusted first.
256
-
257
- ### `routstrd wallet mints info <url>`
258
-
259
- Get info about a specific mint.
260
-
261
- ## Daemon API
262
-
263
- The daemon exposes an OpenAI-compatible HTTP API at `http://localhost:8008`:
264
-
265
- ### `GET /health`
266
-
267
- Health check endpoint.
268
-
269
- ### `GET /v1/models`
270
-
271
- List available models (OpenAI-compatible).
272
-
273
- ### `POST /v1/chat/completions`
274
-
275
- Route a chat completion request.
276
-
277
- ```json
278
- {
279
- "model": "model-id",
280
- "messages": [{ "role": "user", "content": "Hello" }],
281
- "stream": false
282
- }
283
- ```
284
-
285
- ## Configuration
286
-
287
- Config file: `~/.routstrd/config.json`
288
-
289
- | Field | Type | Default | Description |
290
- |-------|------|---------|-------------|
291
- | `port` | number | 8008 | Daemon HTTP port |
292
- | `provider` | string\|null | null | Default provider URL |
293
- | `cocodPath` | string\|null | null | Custom path to cocod executable |
294
- | `mode` | string | `"apikeys"` | Client mode (`apikeys` or `xcashu`) |
295
-
296
- ### Environment Variables
297
-
298
- | Variable | Default | Description |
299
- |----------|---------|-------------|
300
- | `ROUTSTRD_DIR` | `~/.routstrd` | Config directory |
301
- | `ROUTSTRD_SOCKET` | `~/.routstrd/routstrd.sock` | IPC socket path |
302
- | `ROUTSTRD_PID` | `~/.routstrd/routstrd.pid` | PID file path |
303
-
304
- ## Remote Mode
305
-
306
- When `daemonUrl` is configured, commands connect to a remote daemon instead of a local one:
307
- - Client names are suffixed with the last 7 chars of your npub
308
- - All requests are automatically NIP-98 signed using your local nsec
309
- - Local-only commands (`onboard`, `start`, `restart`, `mode`, `logs`, `service`) are disabled
310
-
311
- ## Pi Integration
312
-
313
- When `routstrd onboard` runs, it automatically configures a `routstr` provider in `pi`'s `models.json` with an OpenAI-compatible base URL and API key. This allows pi (the AI coding agent) to use Routstr providers seamlessly.
314
-
315
- ## File Locations
316
-
317
- | Path | Description |
318
- |------|-------------|
319
- | `~/.routstrd/config.json` | Configuration |
320
- | `~/.routstrd/routstr.db` | SQLite database |
321
- | `~/.routstrd/routstrd.sock` | IPC socket |
322
- | `~/.routstrd/routstrd.pid` | PID file |
323
- | `~/.routstrd/logs/YYYY-MM-DD.log` | Daily daemon log files |
324
- | `~/.routstrd/coco-logs/YYYY-MM-DD.log` | Daily Cashu wallet-engine (coco) log files |