# Routstr provider node — instructions for an operator's agent Goal: help an operator set up a Routstr node without exposing the bootstrap admin password or assuming that a running API is a working provider. This file is a standalone entry point for agents without an existing checkout. The commands, Compose file and detailed human steps live in the checked-out repository; read `docs/provider/quickstart.md` and `docs/provider/deployment.md` after cloning. ## Who does what The operator does exactly the items below. Everything else is the agent's job — including DNS records, TLS, the reverse proxy, installing Docker, cloning, checkout, `.env`, port selection, starting Compose, generating keys, dashboard configuration that takes no secret, `check`, verification and every report. Do not ask the operator to confirm or approve an agent step; do it and report it. Each phase marks its operator items and ends at a gate. At a gate, stop and wait for the operator's artifact. Report the blocker, not a fabricated success. ### Operator items (closed list) - **O1 — Answer once, up front.** The domain or subdomain to serve (`https://node.example`), or "private, no domain yet"; and the payout Lightning address (`user@wallet.example`, `lnurl1…`, or an `https://` LNURL-pay endpoint). Nothing else is needed to start. Naming a domain also approves publishing the Nostr listing on first boot. - **O2 — Privileged access.** When an agent step needs host root (installing Docker, DNS, TLS, the reverse proxy, the firewall), ask then; the operator enters it or grants it. - **O3 — Provider secrets.** The operator picks and pays for the upstream provider, pastes its API key into Providers themselves, and decides which model to enable and its pricing. The agent guides and verifies; it never sees the key. - **O4 — Bootstrap password.** Read the one-time admin password from the node logs in the operator's own terminal and rotate it in Settings → Admin Settings. The agent supplies the exact command and URL and never reads that log line. - **O5 — Key backup.** Back up the master key and the NSEC off-host and test a restore (Phase 2). - **O6 — Paid acceptance.** With model, mint, prompt and limit approved, run small paid non-streaming and streaming tests with the operator's own funded client credential — a consumer credential, not node funding and not an admin token. ### Agent must never - Put secrets in chat, shell arguments, Git, captured logs or generated reports, and never ask the operator for one — the admin password, provider API keys, Cashu credentials, CLI tokens and the `nsec`. A credential the agent may *use* but not *read* is `~/.routstr/config.json` (0600), which authorises the Routstr CLI. - Run bare `docker compose up`: stock `compose.yml` publishes port 8000 on all interfaces and starts Tor. Every Compose operation here uses `-f compose.node.yml`. - Run the log command to read the bootstrap password, or paste raw Docker logs or admin responses into a report. - Report a gate as passed without the operator's artifact. ## Default flow (public mode) The default assumes the operator names a subdomain with HTTPS and a reverse proxy forwarding to `127.0.0.1:8000`. The node then publishes its Nostr listing on first boot, which O1 approved. If there is no public URL yet, use private mode and publish later. ### Phase 0 — Host **Agent** - Open by asking O1, before touching the host: - Which domain or subdomain will serve this node (`https://node.example`), or do they want a loopback-only node with no public URL yet? A named domain still needs DNS, TLS and a reverse proxy forwarding to `127.0.0.1:8000`. - Which payout Lightning address should receive settled earnings? It is passed to `start` as `--ln-address` and saved in `.env`; get it now so Phase 1 needs no rerun. - Confirm Docker with the Compose plugin, Python 3, available disk and durable storage; install what is missing (O2 if root is needed). - Clone `https://github.com/Routstr/routstr-core.git` if there is no checkout, check out the tag of the latest release, and inspect the quickstart and deployment guide before running commands. Only if the operator asks to test the current development branch, use that branch and explicitly label it as unreviewed. Reuse an existing checkout and state; do not overwrite `.env` or recreate a wallet. - For public mode, create the DNS record, TLS certificate and reverse proxy entry for the O1 domain (O2 if root is needed), and verify **before** starting that they forward that domain to `127.0.0.1:8000`. If any of that is missing, prefer private mode. The dashboard is protected by the node's own admin password (scrypt-hashed); restricting `/admin` at the proxy (IP allowlist or basic auth) is an optional extra layer, not a setup requirement. The operator still reads the one-time bootstrap password and rotates it (O4). **Operator** - O1: the domain (or "private") and the payout address. - O2: root, only if the agent asks. Gate G0 — Phases 0 and 1 need nothing beyond O1, plus O2 where root is required. ### Phase 1 — Start **Agent** - Check that the loopback port is free, then run (public): ```bash python3 scripts/node_setup.py start --public-url https://node.example --ln-address user@wallet.example ``` or private (nothing published): ```bash python3 scripts/node_setup.py start --private ``` - If another service owns port 8000, keep it untouched and pass `--port 18080`; use that port for `check`, the dashboard URL, the reverse proxy and later `ROUTSTR_NODE_PORT=18080 docker compose -f compose.node.yml …` commands. - Report ref/version, port, reachability and model count. `start` prepares `.env` (never clobbering existing values), starts `compose.node.yml` (loopback only, no Tor, analytics sharing on by default), waits for the local `/v1/info` and `/v1/models`, generates the master key and Nostr identity, and — in public mode — publishes the listing (approved by O1). It also mints a long-lived CLI token and writes it to `~/.routstr/config.json` (0600) for the Routstr CLI; skip that with `--no-cli-token`. If that file already points at another node, `start` leaves it alone and creates no token (see the Routstr CLI section below). A running API with zero models is **not configured**. ### Phase 2 — Back up **Agent** - Hand the operator the numbered list below, with the reveal command. - Afterwards verify that both artifacts exist at the backup target (name, size, hash). Never read their contents. **Operator** (O5) The master key and identity exist as soon as the node boots. Back up exactly two things, off-host and encrypted: 1. The NSEC — the node's Nostr identity key. In your own terminal: ```bash docker compose -f compose.node.yml exec routstr /.venv/bin/python scripts/reveal_nsec.py ``` 2. `routstr_secret.key` — the master key file. Test a restore once, somewhere isolated. Keep the two together: the master key decrypts the `nsec` stored in `keys.db`. Do not ingest the revealed `nsec` or any logs into the agent context. Gate G1 — "both items stored and restore tested." ### Phase 3 — Dashboard **Agent** - Hand the operator the dashboard address (`https://node.example/admin` in public mode, or `http://127.0.0.1:8000/admin` over an SSH tunnel). - After the operator acts, verify model routing, pricing, payout address, mints and relays through the admin API, without printing provider records or secrets. **Operator** - O4: read the generated password privately from `docker compose -f compose.node.yml logs routstr`, log in, and immediately rotate it in Settings → Admin Settings. - O3: add the upstream in Providers with your own API key, enable at least one routable model, and review pricing, payout address, mints and relays. Gate G2 — "password rotated, upstream added, at least one model enabled." ### Phase 4 — Verify and accept **Agent** - Run: ```bash python3 scripts/node_setup.py check --public-url https://node.example ``` Require exit code 0 and a nonzero public model count (exit code 2 means the API is running but not configured). If it fails, diagnose without printing provider records or secrets. This proves discovery only — it is **not** a paid-inference test. - Verify completion, accounting, upstream serving, refund status and payout separately through the admin API. **Operator** - O6: with model, mint, prompt and limit approved, run small paid non-streaming and streaming inference tests with your own funded client credential (not an admin token). Gate G3 — paid-inference verification, or an explicit "discovery only" outcome. ### Handoff Report ref/version, private/public reachability, whether password rotation was confirmed (never the password), model count, backup/restore status, paid-inference verification status and which gates passed. "Local API ready" and "production accepted" are separate outcomes. Never paste raw Docker logs or admin responses. ## Routstr CLI The setup writes a long-lived admin token to `~/.routstr/config.json` (0600), so the [Routstr CLI](https://github.com/routstr/routstr-cli) is ready to operate the node. The agent may use that token but must never print or read it. If that file already pointed at another node, `start` left it alone and minted no token. The CLI only reads `$HOME/.routstr/config.json`, so re-run `start` with `--cli-config /some/dir/.routstr/config.json` and run the CLI as `HOME=/some/dir routstr …`: ```bash git clone https://github.com/routstr/routstr-cli.git cd routstr-cli && bun install routstr instruct # canonical agent guide for this node routstr schema # full command tree as JSON routstr status routstr providers list routstr providers add openrouter --api-key --base-url https://openrouter.ai/api/v1 ``` The token is **full node admin**. Give each agent its own named, expiring token and revoke it when done (**Settings → CLI Tokens**, or `DELETE /admin/api/cli-tokens/{id}`). On a different machine, configure the CLI with `routstr init --node-url --token `. Mint another token with `docker compose -f compose.node.yml exec routstr /.venv/bin/python scripts/create_cli_token.py --name agent`. Never paste the token, or the generated admin password, into a chat. ## Private mode (no public URL yet) Everything above holds, except `HTTP_URL` is unset: the node is loopback-only and publishes nothing. Administer it over an SSH tunnel, and promote it later by setting the public **HTTP URL** in the dashboard (the listing is then published automatically). Publication is an operator decision: ask before promoting.