# ATProto relay deployments

> **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.

two full-network [ATProto](https://atproto.com) relays on independent Hetzner Cloud nodes with k3s:

| | indigo (Go) | zlay (Zig) |
|---|---|---|
| **firehose** | `wss://relay.waow.tech` | `wss://zlay.waow.tech` |
| **jetstream** | `wss://jetstream.waow.tech/subscribe` ([sidecar](https://github.com/bluesky-social/jetstream)) | — |
| **collectiondir** | [sidecar](https://github.com/bluesky-social/indigo/tree/main/cmd/collectiondir) on same endpoint | built-in (inspired by [lightrail](https://tangled.org/microcosm.blue/lightrail)) |
| **health** | [`relay.waow.tech/xrpc/_health`](https://relay.waow.tech/xrpc/_health) | [`zlay.waow.tech/_health`](https://zlay.waow.tech/_health) |
| **metrics** | [`relay-metrics.waow.tech`](https://relay-metrics.waow.tech) | [`zlay-metrics.waow.tech`](https://zlay-metrics.waow.tech) |
| **source** | [bluesky-social/indigo](https://github.com/bluesky-social/indigo) | [zzstoatzz.io/zlay](https://tangled.org/zzstoatzz.io/zlay) |

## try it

both scripts are self-contained [uv scripts](https://docs.astral.sh/uv/guides/scripts/) — no virtualenv or install needed.

### firehose

consumes the raw CBOR firehose using the [atproto](https://github.com/MarshalX/atproto) python SDK.

```bash
# 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://zlay.waow.tech
./scripts/firehose --relay-url wss://bsky.network
```

### jetstream

consumes the simplified JSON firehose via [jetstream](https://github.com/bluesky-social/jetstream) — no atproto SDK needed, just plain websockets.

```bash
# 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

```
.
├── indigo/            # Go relay (indigo) — justfile, deploy configs, terraform
├── zlay/              # zig relay (zlay)  — justfile, deploy configs, terraform
├── shared/deploy/     # helm values shared by both deployments
├── scripts/           # uv scripts — firehose, jetstream, backfill
├── docs/              # architecture, deployment guide, backfill
└── justfile           # root — `just indigo <recipe>` / `just zlay <recipe>`
```

each relay is a `just` module with symmetric recipes:

```bash
just indigo deploy     # deploy Go relay
just indigo status     # check Go relay pods
just zlay deploy       # deploy zig relay
just zlay status       # check zig relay pods
just --list            # see all available recipes
```

## 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](https://whtwnd.com/bnewbold.net/3lo7a2a4qxg2l) — 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](docs/deploying.md) for setup instructions and [docs/architecture.md](docs/architecture.md) for how the pieces fit together.

## prior art

- [a full-network relay for $34 a month](https://whtwnd.com/bnewbold.net/3lo7a2a4qxg2l) by bryan newbold — the definitive guide
- [atproto relay any% speedrun](https://pdsls.dev/at://did:plc:uu5axsmbm2or2dngy4gwchec/com.whtwnd.blog.entry/3lkubavdilf2m) — proof it runs on a raspberry pi
- [running a PDS in kubernetes](https://hayden.leaflet.pub/3m4vfjkr6gc2p) — the app-template helm pattern
- [firehose.network](https://sri.leaflet.pub/3mddrqk5ays27) — 3 public relays deployed globally