mirror of
https://github.com/Routstr/routstrd.git
synced 2026-10-05 20:38:22 +00:00
redshift
b94c0c7020
Register coco-cashu-plugin-npc with the in-process coco wallet so the daemon gets a persistent Lightning address (username@npubx.cash, or an npub fallback) whose paid quotes are synced into the wallet automatically via websocket, mirroring cocod's integration. - coco-client: derive the NPC Nostr signer from the wallet mnemonic (NIP-06), register NPCPlugin after initializeCoco, and expose getNpcAddress/setNpcUsername/syncNpc on the CocodClient interface. New options: enableNpc (default true) and npcBaseUrl. - cocod-client: add the same NPC methods to the legacy socket client as passthroughs to cocod's /npc/address and /npc/username routes, preserving cocod's 402 payment-required status. - http: add GET /wallet/npc/address, POST /wallet/npc/username (402 payment-required flow) and POST /wallet/npc/sync. - cli: add 'routstrd wallet npc address|username <name> [--confirm]|sync'. - tests: mock NPC plugin exercises registration, address formatting, username 402 mapping and sync through the real coco plugin host; legacy passthrough tests; migration test opts out of NPC.
223 lines
4.1 KiB
Markdown
223 lines
4.1 KiB
Markdown
# routstrd
|
|
|
|
Routstr daemon - A CLI tool for managing routstr processes, similar to `cocod` (a Cashu wallet daemon).
|
|
|
|
## Overview
|
|
|
|
routstrd is a Bun-based CLI tool that provides a background daemon for the Routstr protocol. It integrates with `cocod` for wallet management and uses the Routstr SDK to handle provider routing and model discovery.
|
|
|
|
## Routstr for Teams
|
|
|
|
For team-based routing, see [routstrd-auth](https://github.com/Routstr/routstrd-auth).
|
|
|
|
## Features
|
|
|
|
- **Daemon Mode**: Run routstrd as a background HTTP server
|
|
- **Wallet Integration**: Works with cocod for Cashu token management
|
|
- **Provider Routing**: Automatically discovers and routes requests to available providers
|
|
- **Config Management**: Stores configuration in `~/.routstrd/`
|
|
|
|
## Requirements
|
|
|
|
- [Bun](https://bun.sh) runtime
|
|
|
|
```sh
|
|
curl -fsSL https://bun.com/install | bash
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Step 1: Install
|
|
|
|
**Global with bun:**
|
|
```sh
|
|
bun i -g routstrd
|
|
```
|
|
|
|
**OR - From source:**
|
|
```sh
|
|
git clone https://github.com/routstr/routstrd.git
|
|
cd routstrd
|
|
bun install
|
|
bun link
|
|
```
|
|
|
|
### Step 2: Setup & Fund
|
|
|
|
```sh
|
|
routstrd onboard
|
|
routstrd receive <cashu> # receive a Cashu token
|
|
routstrd receive 2100 # to top up 2100 sats with lightning
|
|
```
|
|
|
|
### Step 3: Integrate with Claude Code
|
|
|
|
```sh
|
|
routstrd clients add --claude-code # or --pi-agent / --opencode
|
|
```
|
|
|
|
## Use Routstrd Skill
|
|
|
|
> **Tip:** You can also install the [routstrd skill](https://github.com/Routstr/routstrd/blob/main/SKILL.md) so the agent can manage routstrd for you.
|
|
|
|
## More Commands
|
|
### Start Daemon
|
|
|
|
Start the background daemon:
|
|
|
|
```sh
|
|
routstrd start
|
|
```
|
|
|
|
With custom port:
|
|
```sh
|
|
routstrd start --port 9000
|
|
```
|
|
|
|
The daemon binds to `127.0.0.1` by default. To expose it on another interface:
|
|
```sh
|
|
routstrd start --host 0.0.0.0
|
|
```
|
|
|
|
Only expose the daemon behind appropriate network controls.
|
|
|
|
With specific provider:
|
|
```sh
|
|
routstrd start --provider https://your-provider.com
|
|
```
|
|
|
|
### CLI Commands
|
|
|
|
Check daemon status:
|
|
```sh
|
|
routstrd status
|
|
```
|
|
|
|
Get wallet balance:
|
|
```sh
|
|
routstrd balance
|
|
```
|
|
|
|
Test connection:
|
|
```sh
|
|
routstrd ping
|
|
```
|
|
|
|
Stop the daemon:
|
|
```sh
|
|
routstrd stop
|
|
```
|
|
|
|
### NPC (Lightning Address)
|
|
|
|
The in-process wallet registers the NPC (npubx.cash) plugin, which gives the
|
|
daemon a persistent Lightning address backed by the wallet's Cashu mints.
|
|
Payments to the address are imported into the wallet automatically (websocket
|
|
push, plus manual sync on demand).
|
|
|
|
```sh
|
|
# Show your NPC Lightning address (username@npubx.cash, or npub fallback)
|
|
routstrd wallet npc address
|
|
|
|
# Claim a username (quote first, then confirm to pay the claim fee from the wallet)
|
|
routstrd wallet npc username myname
|
|
routstrd wallet npc username myname --confirm
|
|
|
|
# Manually sync paid NPC quotes into the wallet
|
|
routstrd wallet npc sync
|
|
```
|
|
|
|
Equivalent daemon endpoints: `GET /wallet/npc/address`,
|
|
`POST /wallet/npc/username`, `POST /wallet/npc/sync`.
|
|
|
|
### Daemon API
|
|
|
|
The daemon exposes an HTTP server (default port 8008) with the following endpoints:
|
|
|
|
#### Health Check
|
|
```
|
|
GET /health
|
|
```
|
|
|
|
#### Route Request
|
|
```
|
|
POST /
|
|
```
|
|
|
|
Request body:
|
|
```json
|
|
{
|
|
"model": "model-id",
|
|
"messages": [...],
|
|
"stream": false
|
|
}
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"choices": [...],
|
|
"usage": {...}
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configuration is stored in `~/.routstrd/config.json`:
|
|
|
|
```json
|
|
{
|
|
"port": 8008,
|
|
"host": "127.0.0.1",
|
|
"provider": null,
|
|
"cocodPath": null
|
|
}
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
- `ROUTSTRD_DIR` - Config directory (default: `~/.routstrd`)
|
|
- `ROUTSTRD_SOCKET` - Socket path (default: `~/.routstrd/routstrd.sock`)
|
|
- `ROUTSTRD_PID` - PID file path (default: `~/.routstrd/routstrd.pid`)
|
|
|
|
## Development
|
|
|
|
Install dependencies:
|
|
```sh
|
|
bun install
|
|
```
|
|
|
|
Run CLI:
|
|
```sh
|
|
bun run start
|
|
```
|
|
|
|
Run daemon:
|
|
```sh
|
|
bun run start
|
|
```
|
|
|
|
Typecheck:
|
|
```sh
|
|
bun run lint
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
routstrd/
|
|
├── src/
|
|
│ ├── index.ts # Entry point with shebang
|
|
│ ├── cli.ts # Commander CLI commands
|
|
│ ├── cli-shared.ts # IPC utilities
|
|
│ ├── daemon.ts # HTTP server daemon
|
|
│ └── utils/
|
|
│ └── config.ts # Path configuration
|
|
├── package.json
|
|
└── tsconfig.json
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|