laantungir/routstrd
1
0
Fork 0
mirror of https://github.com/Routstr/routstrd.git synced 2026-10-05 12:28:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
docs/link-session-logs
routstrd/SKILL.md
T
redshift 99f55d3bae chore(wallet): remove the dead legacy cocod client 
The external `cocod` binary was replaced by the in-process Coco wallet
long ago, but its HTTP/unix-socket client kept shipping ~280 lines of
unreachable code next to the wallet contract.

Remove it:

- delete `createCocodClient` (spawns `cocod init`, talks over a unix
  socket, takes a cross-process startup lock) and its helpers
  `resolveCocodExecutable`, `isCocodInstalled`, `normalizeBalances`
  and `CocodBalanceOutput`. None of them are reachable from production
  or from tests; `isCocodInstalled` had no callers at all.
- drop the `options.walletClient || createCocodClient(...)` fallback in
  `createWalletAdapter`. The daemon always passes the in-process client
  built by `createCocoClient()`, so `walletClient` is now required and
  the adapter can no longer silently spawn an external binary.
- drop the vestigial `cocodPath` config key, which only ever fed that
  fallback.
- delete the "legacy cocod client NPC passthroughs" test block, which
  covered only the deleted client.

The shared wallet contract moves from `cocod-client.ts` to
`wallet-client.ts` and loses its `Cocod` prefixes (`WalletClient`,
`WalletRuntimeState`, `WalletHttpError`) — none of it describes cocod
any more. `WalletRuntimeState` avoids colliding with the existing
`WalletState` in `wallet-state.ts`.

Legacy cocod *migration* code is deliberately untouched: `stopLegacyCocod`,
`assertLegacyCocodNotRunning`, `claimLegacyCocodPidFile`, `migration.ts`
and the `legacyCocod*` paths still migrate an existing `~/.cocod` wallet
and fence off a running external daemon.

Net -456 lines. Existing configs that still contain `cocodPath` load
unchanged (unknown keys are ignored) — the key is just no longer written.
2026-10-02 16:59:42 +08:00

557 lines
18 KiB
Markdown
Raw Permalink Blame History

# routstrd CLI Reference
Routstr daemon — a Bun-based CLI tool that runs a background HTTP server for the
Routstr protocol. It carries an in-process Cashu wallet (coco) for payments and
routes LLM requests to available providers.
## Quick Start
```sh
routstrd onboard # Initialize (creates config, sets up the wallet)
routstrd receive 2100 # Top up over Lightning
routstrd start # Start the daemon
routstrd stop # Stop the daemon
```
After onboarding, the daemon listens at `http://localhost:8008` and exposes an
OpenAI-compatible API.
## Commands
### `routstrd onboard`
Initialize routstrd for the first time:
- Creates `~/.routstrd/` (mode 0700) and `~/.routstrd/config.json` (mode 0600)
with defaults (port 8008, host 127.0.0.1, apikeys mode)
- Generates a Nostr identity (`nsec`) for NIP-98 authentication
- Migrates a legacy `~/.cocod` wallet to `~/.routstrd/wallet` if one is present,
stopping any running external `cocod` first
- Initializes the in-process Cashu wallet
- Starts the daemon and configures a client integration
| Option | Description |
|--------|-------------|
| `--opencode` | Set up OpenCode integration (non-interactive) |
| `--openclaw` | Set up OpenClaw integration (non-interactive) |
| `--pi-agent` | Set up Pi Agent integration (non-interactive) |
| `--claude-code` | Set up Claude Code integration (non-interactive) |
| `--hermes` | Set up Hermes integration (non-interactive) |
| `--skip-integration` | Skip integration setup |
Use at most one integration flag. For several clients, run `routstrd clients add`
afterwards. `--skip-integration` cannot be combined with an integration flag.
### `routstrd start`
Start the background daemon process.
| Option | Description |
|--------|-------------|
| `--port <port>` | Port to listen on (default: 8008) |
| `--host <host>` | Bind address (default: 127.0.0.1) |
| `-p, --provider <provider>` | Default provider to use |
### `routstrd daemon`
Run the daemon in the foreground (same options as `start`). Useful for debugging
and for process supervisors that expect a non-forking process.
### `routstrd stop`
Stop the background daemon.
### `routstrd restart`
Restart the daemon (stops if running, then starts). Same options as `start`.
### `routstrd status`
Check daemon and wallet status. Returns JSON with current state.
### `routstrd ping`
Test connectivity to the daemon.
### `routstrd balance`
Get wallet and API key balances. Shows per-mint wallet balances, per-key API
balances, and a grand total (all in sats).
| Option | Description |
|--------|-------------|
| `--api-keys` | List all stored API keys (baseUrl + key + balance) |
| `--delete-api-keys <baseUrl>` | Delete the API key stored for a provider base URL (refunds its balance first) |
| `--mint-url <url>` | Mint to refund the deleted API key balance to (defaults to the active wallet mint) |
### `routstrd refund`
Refund pending tokens and API keys to a mint.
| Option | Default | Description |
|--------|---------|-------------|
| `-m, --mint-url <mintUrl>` | active wallet mint | Mint URL to refund to |
| `-y, --yes` | false | Skip confirmation prompt |
| `--xcashu` | false | Refund xcashu tokens only |
### `routstrd models`
List available routstr21 models (discovered via Nostr).
| Option | Description |
|--------|-------------|
| `-r, --refresh` | Force refresh models from Nostr |
| `-m, --model <id>` | Show the providers serving a specific model |
### `routstrd usage`
Show recent usage logs and total sats cost.
| Option | Default | Description |
|--------|---------|-------------|
| `-n, --limit <number>` | 10 | Number of recent entries (max 1000) |
Shows timestamp, model, provider, sats cost, token counts, and request ID for
each entry.
### `routstrd history`
Show wallet transaction history.
| Option | Default | Description |
|--------|---------|-------------|
| `-n, --limit <number>` | 50 | Number of entries to show |
| `--offset <number>` | 0 | Number of entries to skip |
| `-t, --type <type...>` | all | Filter by transaction type (`send`, `receive`, `mint`, `melt`). Repeatable or comma-separated |
| `-i, --id <id>` | | Show a single transaction by its ID (prints one summary line; add `--verbose` for full details) |
| `-v, --verbose` | false | Show full details including encoded Cashu tokens |
| `--json` | false | Output raw JSON with token objects (no encoding) |
### `routstrd providers`
List and manage providers (subcommand required).
#### `routstrd providers list`
List all providers with their enabled/disabled status. Shows index, status, and
base URL.
| Option | Description |
|--------|-------------|
| `--refresh` | Force re-fetch all Nostr events and refresh models from every enabled provider |
```
Providers (12 total, 2 disabled):
[0] enabled https://provider1.example.com
[1] enabled https://provider2.example.com
[2] DISABLED https://provider3.example.com
```
#### `routstrd providers disable <indices...>`
Disable providers by their index numbers.
```sh
routstrd providers disable 0 2 5
```
#### `routstrd providers enable <indices...>`
Enable providers by their index numbers.
```sh
routstrd providers enable 0 2 5
```
#### `routstrd providers reviews`
Show all known providers with their stored review events and event IDs.
### `routstrd cooldowns`
List every provider and model the router is currently skipping because of a
cooldown. Cooldowns are scoped: a provider-wide entry blocks every model on
that provider, a model-scoped entry blocks only that model. Entries lift
automatically once the cooldown window (210s) elapses — nothing needs to be
cleared by hand.
| Option | Default | Description |
|--------|---------|-------------|
| `--json` | false | Print the raw daemon response (timestamps and remaining ms per entry) |
```
Cooldowns (210s window)
2 active across 2 providers:
PROVIDER https://api.nonkycai.com/ expires in 3m 20s
MODEL https://ai.redsh1ft.com/ deepseek-v4.1-flash expires in 2m 30s
```
Reads `GET /cooldowns` from the daemon; a daemon built before this command
existed has no such endpoint and must be restarted on a newer build.
### `routstrd clients`
List and manage API clients (subcommand required).
| Option | Description |
|--------|-------------|
| `--manual-refresh` | Refresh routstr21 models and all client integrations now |
| `--disable-automatic-refresh` | Disable the daemon's scheduled refresh job |
| `--enable-automatic-refresh` | Re-enable the daemon's scheduled refresh job |
The daemon refreshes models and client integrations on a schedule (every 21
minutes by default). Use `--manual-refresh` to do it on demand, and
`--disable-automatic-refresh` to stop the scheduled job — the setting is stored
in the daemon's `config.json` (`autoRefresh.enabled`) and takes effect without a
restart.
```sh
routstrd clients --manual-refresh # refresh models + integrations now
routstrd clients --disable-automatic-refresh # no scheduled refresh
routstrd clients --enable-automatic-refresh # scheduled refresh back on
```
#### `routstrd clients list`
List all registered clients with their ID, name, API key, and creation date.
#### `routstrd clients add`
Add a new client or set up a client integration.
| Option | Description |
|--------|-------------|
| `-n, --name <name>` | Client name (required when not using integration flags) |
| `--opencode` | Set up OpenCode integration |
| `--openclaw` | Set up OpenClaw integration |
| `--pi-agent` | Set up Pi Agent integration |
| `--claude-code` | Set up Claude Code integration |
| `--hermes` | Set up Hermes integration |
```sh
routstrd clients add --opencode --pi-agent --claude-code # multiple integrations
routstrd clients add -n "My App" # generic client
```
Returns the client ID and API key for use with the OpenAI-compatible API.
#### `routstrd clients delete <id>`
Delete a registered client by its ID.
### `routstrd npubs`
Manage registered npubs and their roles/names (subcommand required). Management
commands route through the auth proxy (`--auth-url`) and use NIP-98 auth.
| Command | Description |
|---------|-------------|
| `routstrd npubs list` | List registered npubs with role and display name |
| `routstrd npubs register [--name <name>]` | Register yourself as the first admin (bootstrap only) |
| `routstrd npubs add <npub> [--role <role>] [--name <name>]` | Add an npub (accepts hex or npub1...); defaults to the `user` role |
| `routstrd npubs update <npub> [--role <role>] [--name <name>]` | Update role and/or name (admin only) |
| `routstrd npubs delete <npub>` | Delete an npub |
### `routstrd remote [url]`
With no URL, print the configured remote daemon. Pass a URL to configure one — a
Nostr identity (nsec/npub) is generated automatically for NIP-98 authentication.
| Option | Description |
|--------|-------------|
| `--auth-url <authUrl>` | URL of the auth proxy used by management commands (`npubs`, `clients`, `usage`) |
```sh
routstrd remote # show current remote
routstrd remote https://your-remote-daemon.com # configure one
```
### `routstrd local`
Switch back to local daemon mode (clears the configured remote daemon URL).
### `routstrd refresh`
Refresh routstr21 models from Nostr and re-run integrations for all registered
clients. Equivalent to `routstrd clients --manual-refresh`.
### `routstrd update`
Update routstrd to the latest version. Standalone-binary installs update
in place; npm/bun installs are updated through the package manager.
### `routstrd mode`
Interactive prompt to set the client mode:
1. **lazyrefund/apikeys** (default) — Pseudonymous accounts kept with Routstr
nodes, refunded after 5 mins if unused.
2. **xcashu** (coming soon) — Balances never kept with nodes, all refunded in
response.
Changing mode restarts the daemon automatically.
### `routstrd monitor` / `routstrd top`
Open an interactive TUI (htop-like) for usage monitoring. `top` is an alias.
### `routstrd logs`
View daemon logs.
| Option | Default | Description |
|--------|---------|-------------|
| `-f, --follow` | false | Follow log output (like `tail -f`) |
| `-c, --coco` | false | Show Cashu wallet-engine (coco) logs instead of daemon logs |
| `-n, --lines <number>` | 50 | Number of lines to show |
| `-r, --recent` | false | List recent request IDs with their model |
| `-i, --request-id <id>` | | Only show log lines for a specific request ID |
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.
### `routstrd service`
Manage routstrd as a system service using PM2, so it survives reboots.
| Command | Description |
|---------|-------------|
| `routstrd service install` | Install and start routstrd under PM2 |
| `routstrd service uninstall` | Stop and remove routstrd from PM2 |
| `routstrd service logs` | View PM2 logs for routstrd |
## Wallet Commands
New wallets trust two mints out of the box: `https://mint.minibits.cash/Bitcoin`
and `https://mint.cubabitcoin.org`. `https://mint.minibits.cash/Bitcoin` is the
default mint, and the default is used when a wallet command does not include
`--mint-url`. An existing wallet keeps whatever default it already has; the
shipped mints are only added as trusted, never as the default. Use
`routstrd wallet mints add <url>` to trust another mint.
### `routstrd send <target>` / `routstrd receive <value>`
Shortcuts for the common wallet operations:
| Command | Behaviour |
|---------|-----------|
| `routstrd send 2100` | Numeric target → create a Cashu token for that many sats |
| `routstrd send lnbc1...` | Non-numeric target → pay that Lightning invoice |
| `routstrd receive 2100` | Numeric value → create a Lightning invoice for that many sats and wait for payment |
| `routstrd receive cashuB...` | Non-numeric value → receive that Cashu token |
Both accept `--mint-url <url>`.
### `routstrd wallet status`
Check wallet status.
### `routstrd wallet doctor`
Diagnose conflicting wallets — the current routstrd wallet versus a legacy
`cocod` wallet.
### `routstrd wallet unlock <passphrase>`
Unlock the wallet with a passphrase.
### `routstrd wallet balance`
Get wallet balance.
### `routstrd wallet cleanup`
Clear stuck pending/in-flight wallet operations.
| Option | Default | Description |
|--------|---------|-------------|
| `--mint-url <url>` | all mints | Only clean up operations for this mint URL |
| `--min-age <hours>` | 168 | Minimum age for reclaiming sends and cancelling melts (expired mint quotes are always failed) |
| `--dry-run` | false | Report what would be cleaned without applying changes |
| `-y, --yes` | false | Skip confirmation prompt |
### `routstrd wallet receive cashu <token>`
Receive funds via a Cashu token.
### `routstrd wallet receive bolt11 <amount>`
Create a Lightning invoice to receive funds. Displays a QR code.
| Option | Description |
|--------|-------------|
| `--mint-url <url>` | Mint URL to use |
### `routstrd wallet send cashu <amount>`
Create a Cashu token to send.
| Option | Description |
|--------|-------------|
| `--mint-url <url>` | Mint URL to use |
### `routstrd wallet send bolt11 <invoice>`
Pay a Lightning invoice.
| Option | Description |
|--------|-------------|
| `--mint-url <url>` | Mint URL to use |
### `routstrd wallet mints list`
List configured wallet mints. Includes the mints trusted by default (`https://mint.minibits.cash/Bitcoin`, `https://mint.cubabitcoin.org`) plus any added manually.
### `routstrd wallet mints add <url>`
Add a new mint by URL.
### `routstrd wallet mints set-default <url>`
Set the persistent default mint. If necessary, the mint is added as trusted first.
### `routstrd wallet mints info <url>`
Get info about a specific mint.
### `routstrd wallet npc`
NPC (npubx.cash) Lightning address operations.
| Command | Description |
|---------|-------------|
| `routstrd wallet npc address` | Show this wallet's NPC Lightning address |
| `routstrd wallet npc username <name> [--confirm]` | Claim an NPC username; `--confirm` pays the claim fee |
| `routstrd wallet npc sync` | Manually sync paid NPC quotes into the wallet |
## NWC (Nostr Wallet Connect)
Connect an external Lightning wallet and let it fund the Cashu wallet.
| Command | Description |
|---------|-------------|
| `routstrd nwc connect [connection-string]` | Connect via `nostr+walletconnect://...` (prompts if omitted) |
| `routstrd nwc disconnect` | Disconnect from the NWC wallet |
| `routstrd nwc status` | Show connection status and wallet info |
| `routstrd nwc fund <amount>` | Manually fund the Cashu wallet from the connected NWC wallet |
### `routstrd nwc auto-refill on`
Enable automatic wallet refill from NWC.
| Option | Default | Description |
|--------|---------|-------------|
| `--threshold <sats>` | 500 | Refill when the Cashu balance drops below this |
| `--amount <sats>` | 1000 | Refill this many sats at a time |
| `--cooldown <seconds>` | 300 | Minimum time between refills |
### `routstrd nwc auto-refill off`
Disable auto-refill.
## Daemon API
The daemon exposes an OpenAI-compatible HTTP API at `http://localhost:8008`:
### `GET /health`
Health check endpoint.
### `GET /v1/models`
List available models (OpenAI-compatible).
### `POST /v1/chat/completions`
Route a chat completion request.
```json
{
"model": "model-id",
"messages": [{ "role": "user", "content": "Hello" }],
"stream": false
}
```
The incoming request path is forwarded to the provider, so the Anthropic
Messages API (`POST /v1/messages`) and the OpenAI Responses API
(`POST /v1/responses`) are proxied in their own formats as well.
## Configuration
Config file: `~/.routstrd/config.json`
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `port` | number | 8008 | Daemon HTTP port |
| `host` | string | `"127.0.0.1"` | Bind address |
| `provider` | string\|null | null | Default provider URL |
| `mode` | string | `"apikeys"` | Client mode (`apikeys` or `xcashu`) |
| `maxTokens` | number | 64000 | Completion budget applied when a client sets no output-token limit |
| `daemonUrl` | string | — | Remote daemon URL (set by `routstrd remote`) |
| `authUrl` | string | — | Auth proxy URL for management commands |
| `nsec` | string | — | Nostr secret key for NIP-98 auth |
| `relays` | string[] | — | Nostr relays to use for discovery |
| `routstrPubkey` | string | — | Override the Routstr announcement pubkey |
| `routstrModelsPubkey` | string | — | Override the routstr21 models pubkey |
| `nwc` | object | — | NWC settings (`mode`, `connectionString`, `autoRefill`) |
| `autoRefresh` | object | `{ enabled: true }` | Scheduled refresh job settings (`enabled`, `intervalMs`) |
| `requestResponseLogging` | object | — | Request/response log sink settings |
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `ROUTSTRD_DIR` | `~/.routstrd` | Config directory |
| `ROUTSTRD_SOCKET` | `~/.routstrd/routstrd.sock` | IPC socket path |
| `ROUTSTRD_PID` | `~/.routstrd/routstrd.pid` | PID file path |
| `ROUTSTRD_WALLET_DIR` | `~/.routstrd/wallet` | In-process Cashu wallet data directory |
| `ROUTSTRD_WALLET_PID` | `<wallet>/wallet.pid` | In-process wallet lock path |
| `COCOD_DIR` | `~/.cocod` | Legacy external cocod compatibility directory |
## Remote Mode
When `daemonUrl` is configured, commands connect to a remote daemon instead of a
local one:
- Client names are suffixed with the last 7 chars of your npub
- All requests are automatically NIP-98 signed using your local nsec
- Local-only commands (`onboard`, `start`, `restart`, `mode`, `logs`, `service`)
are disabled
Run `routstrd local` to switch back.
## Pi Integration
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.
## File Locations
| Path | Description |
|------|-------------|
| `~/.routstrd/config.json` | Configuration |
| `~/.routstrd/routstr.db` | SQLite database |
| `~/.routstrd/routstrd.sock` | IPC socket |
| `~/.routstrd/routstrd.pid` | PID file |
| `~/.routstrd/wallet/` | In-process Cashu wallet data (`config.json`, `coco.db`, `wallet.pid`) |
| `~/.routstrd/logs/YYYY-MM-DD.log` | Daily daemon log files |
| `~/.routstrd/coco-logs/YYYY-MM-DD.log` | Daily Cashu wallet-engine (coco) log files |
## Development
```sh
bun install
bun run lint # tsc --noEmit
bun test
bun run build # bundles dist/index.js and dist/daemon/index.js
```
End-to-end smoke test against a running daemon (needs a funded client API key):
```sh
ROUTSTRD_API_KEY=<api-key> bun run smoke <model-id> [model-id ...]
```
Reference in New Issue View Git Blame Copy Permalink