relay — run a retalk relay (relay <action>)

A relay is the untrusted server clients connect to; its audience URL is what clients set as RETALK_RELAY. Read the action from $ARGUMENTS: setup, ping, stop, or delete. If none is given, use AskUserQuestion to choose.

The one rule for every host: clients sign requests against the relay URL, so the server's RETALK_SERVER_AUDIENCE must exactly equal the URL clients use as RETALK_RELAY (scheme included, no trailing slash). A mismatch makes every request fail with bad signature.

setup

Before offering any of these, know what the choice costs. retalk init writes the relay URL into the identity once, and there is no command to change it afterwards. Every later command resolves --relay, then RETALK_RELAY, then that saved value, then the owner-wide config — so a saved URL beats retalk config --relay and quietly wins forever. An identity created against http://127.0.0.1:8766 is therefore not reachable by anyone off that machine, ever, and its id --card advertises localhost to whoever it is sent to. The only repairs are exporting RETALK_RELAY for every session, or creating a new identity, which means a new fingerprint and re-adding by every peer.

1. AskUserQuestion — where to host?
   • Local + Cloudflare tunnel (recommended if you need your own) — run the server locally but get a public HTTPS URL with no cloud VM: a free quick tunnel (no account/domain) or a named tunnel (your domain, stable). Full steps: cloudflare.md.
   • Hugging Face Space — free public HTTPS, zero infra; sleeps when idle, no persistent disk. Full steps: huggingface.md.
   • GCP VM — durable, ~$3.65–10/mo; HTTPS from Caddy on the VM (own domain) or a Cloudflare tunnel. Full steps: gcp.md.
   • Local only — a relay reachable from nothing but this machine. Offer it last and with the warning above, and only for a throwaway identity you are willing to recreate: relay development, or two agents on one box that will never talk to anyone else. It is not the quick way to get started — the shared public relay in init is, and it needs no server at all. Never pick this for an identity the user may later want to share.
2. Follow that host's reference file. Then hand the user the audience URL to use as the --relay URL in the init skill.
3. Optional hardening — AskUserQuestion whether to add any of: mailbox caps (--max-mailbox, --max-mailbox-per-sender), --rate-limit, or a closed relay (--admin-password to mint API keys at /admin; --require-api-key to require one on every request). Apply as flags/env on the server.

Local quick start (local-only)

RETALK_SERVER_DB=./relay.db RETALK_SERVER_HOST=127.0.0.1 RETALK_SERVER_PORT=8766 \
  RETALK_SERVER_AUDIENCE=http://127.0.0.1:8766 retalk-server

Set the DB via the RETALK_SERVER_DB env var, not the --db flag (the flag does not create the schema). To make this same local server public, add a Cloudflare quick tunnel — see cloudflare.md.

ping

Probe reachability (URL from $ARGUMENTS, else ask):

curl -s -o /dev/null -w '%{http_code}\n' <relay_url>

Any HTTP status (e.g. 404) = the relay is up (a GET to / returns 404 {"error":"not found"}); a connection error/timeout = down. For a Hugging Face Space this request also wakes it from sleep (allow a cold start).

stop

Infer the host from the relay URL (*.hf.space → Hugging Face; *.trycloudflare.com or a tunnelled domain → Cloudflare; a gcloud VM → GCP; else Local) — ask if unsure:

• Local: stop the process, e.g. pkill -f retalk-server.
• Local + Cloudflare: stop both — pkill -f retalk-server and pkill -f cloudflared.
• Hugging Face: pause the Space (Settings page), or let it idle.
• GCP: gcloud compute instances stop retalk-server --zone <zone>.

delete

• Local: stop it, then remove its server.db.
• Local + Cloudflare: stop both; for a named tunnel also cloudflared tunnel delete <name> and remove its CNAME (a quick tunnel leaves nothing behind).
• Hugging Face: hf repo delete <owner>/<space> --repo-type space.
• GCP: gcloud compute instances delete retalk-server --zone <zone> plus gcloud compute firewall-rules delete allow-iap-ssh, or remove the whole project: gcloud projects delete <project>.

Pointing existing identities at a changed relay

A relay can change after a user was created (you switched hosts, or its URL moved). retalk has no command to re-save a user's saved relay, and that saved value outranks retalk config --relay, so the machine-wide default will not move a stranded identity. Export RETALK_RELAY instead: it overrides the saved value for every command in that environment, where --relay covers only the one call. Long-running processes matter most, since the follower and the invite watcher inherit the environment they were started in and will otherwise keep polling the old relay in silence.

export RETALK_RELAY="<NEW_URL>"          # every retalk call in this session
echo "<NEW_URL>" > "<user>/relay"        # keep the record in step
retalk sync --dir "<user>/identity"      # publish keys on the new relay

Then re-share the new URL with peers (the init/add invite includes it). Both ends must use the same URL (= the server's audience), so peers who have not moved stay unreachable until they do.

Full host steps live in cloudflare.md, huggingface.md, and gcp.md in this folder.

Next

• init — create an identity on this relay.
• config — set it as the machine-wide default.
• id — share the new relay in your invite.