archy/apps/routstr

Routstr provider — development candidate

This is the local-server foundation of docs/routstr-fips-llama-integration.md. It is not yet lifecycle-qualified or catalog-published. The node's FIPS gateway (/routstr/v1/models, /routstr/v1/chat/completions) serves it to mesh peers only after the operator sets routstr_selling on; it has not yet been exercised between two real nodes. Do not install it over an existing Routstr wallet/database to test it.

Package boundary

• Builds Routstr Core main at immutable source commit 8ce9ef69fc1b5ecd6f92f1baf54d8c2620ea0e89 (2026-10-24; v0.5.0 plus 87 commits, upstream CI green), using its frozen uv dependency lock. It includes upstream #829 and #872: an X-Cashu payment is refunded when forwarding or settlement fails (connect or read timeout, upstream error), in the error response's x-cashu header and as saved change. No release is tagged after v0.5.0 yet; move to the next tag once there is one. Routstr reports its version as 0.5.0+g8ce9ef6.
• Upstream's image workflow publishes moving latest images; we therefore build from reviewed source instead of inventing an upstream versioned image tag. The base image is pinned by multi-arch index digest; a production image build remains an acceptance gate.
• Host API binds only 127.0.0.1:8200. auth: local prevents the app gate from opening external listeners. There is deliberately no browser launch interface.
• Root filesystem is read-only; /data contains the database, encryption key, relative .wallet directory and logs. /tmp is disposable.
• A dedicated generated admin secret enters through Podman secrets. No appliance Nostr private key is copied. Admin credential UI is not wired yet.
• Upstream is the node's private llama-server (http://llama-server:8080/v1), authenticated with llama-server's generated key (llama-server-api-key).
• The node ecash wallet owns payment settings. CASHU_MINTS renders from {{ECASH_MINTS}} (the wallet's accepted mints; Minibits by default) and RECEIVE_LN_ADDRESS from {{ECASH_LN_ADDRESS}} (the wallet's Minibits address), so earnings above Routstr's 210-sat payout floor are paid to the node wallet, where the existing claim flow redeems them. Never leave CASHU_MINTS empty: Routstr then silently trusts its built-in mint.minibits.cash default.
• Routstr's database copy of settings wins over the environment after the first start, so archy-start.py (the image's PID 1) re-applies the mints and payout address through the admin API on every start. Mint changes made in Routstr's own admin UI are therefore overwritten by the node wallet's list.
• The archy-llama model is priced once at install defaults ($1 / $2 per million prompt / completion tokens, plus Routstr's 1% fee). Routstr refuses to serve an unpriced model; an operator's later price is never replaced.
• No Nostr identity or publication address; analytics and upstream 5xx retries are disabled.
• Upstream starts exchange-rate/background tasks; disabled pricing refresh does not establish zero external traffic. Runtime egress qualification is pending.
• TCP health means the API listener is up, not that inference/payments are ready.

llama-server connection contract

The reviewed upstream GenericUpstreamProvider accepts an OpenAI-compatible base URL and optional API key. The initial target is llama.cpp's llama-server:

• provider base URL points at the private runtime's /v1 API;
• fetch /v1/models, then explicitly import/enable the chosen model and pricing;
• enforce a stable model alias and bounded context/output/concurrency;
• verify usage token accounting and the actual model's chat template;
• do not advertise tool/streaming support until tested with that model;
• keep the raw runtime off external listeners and give it a dedicated upstream key.

A candidate managed runtime now lives in apps/llama-server; its source build and lifecycle still need qualification. Private network isolation, configuration RPC/key handoff and model acquisition UI are still to be implemented. There is intentionally no automatic model download or default cloud upstream. Merely sharing archy-net does not isolate the runtime from other installed apps; that is a remaining security gate.

Payment modes (observed at the pinned revision)

X-Cashu: <token> pays for one request and returns change in the X-Cashu response header (the whole token when the request is refused). Authorization: Bearer <token> instead funds a server-side sk- balance and returns no change until POST /v1/balance/refund, which replays the same token if repeated. Buyers must use X-Cashu; the existing Archipelago clients are fixed by the ngit proposal "fix(routstr): pay per request with X-Cashu so change is refunded".

A buyer whose reply never carried its change claims it over the mesh at POST /routstr/v1/balance/refund with the original token: the seller gateway forwards only that token to Routstr's POST /v1/balance/refund, which returns the change it saved for the request (425 while the request is still running).

Upstream routstr/balance.py has persisted refund retrieval and pending outcomes; routstr/upstream/base.py emits millisatoshi cost headers. Neither is evidence that an ambiguous completion can safely be resubmitted. Recovery must not issue another payment or inference request by default.

Source-only checks

From the repository root:

bash scripts/validate-app-manifest.sh apps/routstr/manifest.yml
python3 -m unittest discover -s tests/routstr-provider -p 'test_*.py' -v

These tests do not build/start containers, contact a provider, or touch wallets. For future disposable builds, use docker/routstr as the build context. For node packaging the manifest references /opt/archipelago/docker/routstr, following the normal runtime payload contract. Do not stage this on a live node for acceptance without an explicit test plan and isolated data.