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.

FileKindSize
SKILL.mdskill md6.0 KB
cloudflare.mdmarkdown2.3 KB
gcp.mdmarkdown4.2 KB
huggingface.mdmarkdown2.5 KB
---
name: relay
description: 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: 322kUpdated 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: 198kUpdated 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: 119kUpdated 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