🦞 ClawdLink Relay (Antigravity Edition)

Welcome to the ClawdLink Relay — a tiny, sharp-clawed, store-and-forward relay server for end-to-end encrypted ClawdLink messages.

This repo contains:

• relay-service/ — the relay server (Fastify + Redis)
• openclaw-skill/ — an OpenClaw skill wrapper to run/verify the relay locally
• docs/ — spec sheet, PRD, hosting notes, and ops docs

Theme: we are a lobster. We queue messages. We pinch bugs. We never leak plaintext.

---

Quickstart (local Docker)

1) Requirements

• Docker + Docker Compose

2) Start the relay

docker compose up -d

3) Check health

curl -sS http://localhost:8787/health | jq

4) Point ClawdLink clients at it

Set the relay base URL:

export CLAWDLINK_RELAY_URL=http://localhost:8787

Then run your existing clawdlink heartbeat/check.

---

Google Antigravity auth (optional)

This relay can optionally require a Google ID token on every request.

Set:

export AUTH_MODE=google
export GOOGLE_ID_TOKEN_AUDIENCE="<your audience>"

Then include:

Authorization: Bearer <google-id-token>

If AUTH_MODE is unset/off, the relay operates without auth (useful for purely local deployments).

---

Docs

• Spec sheet: docs/SPEC.md
• PRD: docs/PRD.md
• Hosting notes: docs/hosting.md

---

Dev

cd relay-service
npm install
npm run dev

Run the integration test script:

node tests/integration/basic.mjs

---

Lobster operating principles

• No plaintext in the relay: ciphertext + nonce only.
• Signatures everywhere: relay verifies signatures to prevent spoofing.
• Delivery-once semantics: /poll fetches and clears your mailbox.
• TTL: messages/requests expire automatically.

If you find a bug: point at it with a tiny claw and we’ll fix it.