zzstoatzz.io / relay
declarative relay deployment on hetzner relay.waow.tech
atproto
fork atom
Just 31.9%
HCL 8.1%
Other 60.0%
13 1 0

Clone this repository

https://tangled.org/zzstoatzz.io/relay
git@tangled.org:zzstoatzz.io/relay

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

relay.waow.tech#

experimental — this is a personal project for learning ATProto infrastructure. the endpoints below may go down, lose data, or change without notice. do not depend on them for anything that matters.

a full-network ATProto relay running on a single Hetzner Cloud node with k3s. a jetstream instance runs alongside it, re-encoding the relay's CBOR firehose into plain JSON over websockets. a collectiondir sidecar indexes (DID, collection) pairs from the firehose and serves com.atproto.sync.listReposByCollection for TAP crawlers.

relay endpoint: wss://relay.waow.tech — raw CBOR firehose (com.atproto.sync.subscribeRepos)

jetstream endpoint: wss://jetstream.waow.tech/subscribe — same data, JSON over websockets

collection directory: https://relay.waow.tech/xrpc/com.atproto.sync.listReposByCollection — paginated DID lists per collection (indie PDS hosts backfilled, bsky shard backfill pending)

health check: https://relay.waow.tech/xrpc/_health

metrics dashboard: https://relay-metrics.waow.tech (public, anonymous read-only)

try it#

both scripts are self-contained uv scripts — no virtualenv or install needed.

firehose#

consumes the raw CBOR firehose using the atproto python SDK.

# watch posts scroll by for 10 seconds
./scripts/firehose

# run longer, filter by collection
./scripts/firehose --duration 30
./scripts/firehose --collection app.bsky.feed.like
./scripts/firehose --duration 0  # forever (ctrl-c to stop)

# point at a different relay
./scripts/firehose --relay-url wss://bsky.network

jetstream#

consumes the simplified JSON firehose via jetstream — no atproto SDK needed, just plain websockets.

# watch all events for 10 seconds
./scripts/jetstream

# filter to specific collections
./scripts/jetstream --collection app.bsky.feed.post
./scripts/jetstream --collection app.bsky.feed.like --collection app.bsky.graph.follow

# run longer, or forever
./scripts/jetstream --duration 30
./scripts/jetstream --duration 0  # forever (ctrl-c to stop)

# point at a different jetstream instance
./scripts/jetstream --url wss://jetstream1.us-east.bsky.network

what's here#

.
├── docs/              # architecture, deployment guide, backfill
├── scripts/           # uv scripts — firehose, jetstream, backfill
├── justfile           # all commands: deploy, status, logs, backfill, etc.
├── infra/             # terraform — hetzner server + k3s
└── deploy/            # helm values + k8s manifests

why#

the ATProto relay is the piece of infrastructure that aggregates writes from every PDS on the network into a single firehose stream. downstream services (appviews, feed generators, labelers) subscribe to a relay instead of crawling thousands of individual servers.

running one is surprisingly cheap — the relay binary uses modest CPU and memory, and storage requirements are manageable. the main cost driver is bandwidth, which is why Hetzner (unlimited 1 Gbps) is a good fit.

this repo is a template for deploying your own. everything is declarative: terraform for the VM, helm for the workloads, a justfile to tie it together. see docs/deploying.md for setup instructions and docs/architecture.md for how the pieces fit together.

prior art#