Skip to content

xhluca/agent-talk / skills/relay

Set up, check, stop, or delete a retalk relay server (retalk-server). Use when the user needs their OWN relay rather than an existing URL. Invoke as `relay setup`, `relay ping`, `relay stop`, or `relay delete`. Uses AskUserQuestion to pick the host (Local / Local+Cloudflare / Hugging Face / GCP) and gather settings.

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.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall