zzstoatzz.io
claude up some atproto stuff
1---
2name: spacedust
3description: Connect to the Spacedust real-time interactions firehose for AT Protocol. Use when building live notifications, real-time counters, activity feeds, or any feature that needs to react to interactions as they happen.
4user-invocable: true
5---
6
7# spacedust — real-time interactions firehose
8
9Streams link events from the entire AT Protocol network over WebSocket with client-side filtering.
10
11**Live docs:** https://spacedust.microcosm.blue
12**Source:** https://github.com/at-microcosm/microcosm-rs/tree/main/spacedust
13
14## connecting
15
16```
17wss://spacedust.microcosm.blue/subscribe?wantedSources=...&wantedSubjectDids=...
18```
19
20Sources use the same `collection:path` format as Constellation.
21
22## filter params
23
24| parameter | what it filters | max values |
25|-----------|----------------|-----------|
26| `wantedSubjects` | specific AT-URIs | 50,000 |
27| `wantedSubjectDids` | DIDs (all interactions with their content) | 10,000 |
28| `wantedSubjectPrefixes` | URI/DID prefixes | 100 |
29| `wantedSources` | interaction types | 1,000 |
30| `instant` | bypass 21-second delay buffer | boolean |
31
32**Filter logic:** subject params are **OR**. Sources are **AND** with subjects. So `wantedSubjectDids=X&wantedSources=app.bsky.feed.like:subject.uri` = "likes on X's content."
33
34## message format
35
36```json
37{"kind":"link","origin":"live","link":{"operation":"create","source":"app.bsky.feed.like:subject.uri","source_record":"at://did:plc:.../app.bsky.feed.like/3lv4ouczo2b2a","source_rev":"3lv4ouczp1x2a","subject":"at://did:plc:.../app.bsky.feed.post/3lgwdn7vd722r"}}
38```
39
40The current (lightweight) version emits only `operation: "create"` — it keeps no history, so it cannot emit `delete` events and offers no replay window (`origin` is always `"live"`). A future overhaul adds a full forward-link index with hydrated deletes and replay.
41
42## dynamic filter updates
43
44Send JSON on the open connection to replace filters without reconnecting:
45
46```json
47{"type": "options_update", "payload": {"wantedSubjectDids": ["did:plc:..."], "wantedSources": ["app.bsky.graph.follow:subject"]}}
48```
49
50## quick start
51
52```bash
53# watch for new followers of bsky.app
54websocat "wss://spacedust.microcosm.blue/subscribe?wantedSources=app.bsky.graph.follow:subject&wantedSubjectDids=did:plc:z72i7hdynmk6r22z27h6tvur"
55```
56
57## notes
58
59- events are buffered 21 seconds to filter quickly-undone interactions; `instant=true` bypasses this
60- unauthenticated, no API key needed