Worker discovery
How workers and ORK find each other over a Hyperswarm DHT topic
If ORK, worker, or thing are unfamiliar, read terminology first.
Overview
Workers and ORK find each other over a shared Hyperswarm DHT topic — a 32-byte rendezvous key both sides join before any RPC takes place. No coordination server is required. Once a worker joins the topic, ORK detects the peer and runs the discovery and registration sequence.
Operating modes
A DHT round-trip is only needed when ORK and the worker run in separate processes:
| Mode | How worker connects | When to use |
|---|---|---|
| Same-process | startWorker(W, { ork }) registers directly with the in-memory ORK instance — no DHT join | Development, get-started tutorials, single-process sites |
| Multi-process | startWorker(W) joins the DHT topic; ORK detects it as a new peer | Production microservices, workers on separate hosts |
The deployment topologies page covers when to pick each packaging shape.
Topic coordination
In multi-process mode, ORK and the worker must join the same topic. Two options:
Auto-generated (default) — startWorker() generates a random 32-byte hex topic, writes it to /tmp/mdk/.dht-topic, and joins the DHT; getOrk() reads the same file and joins the matching topic.
Explicit topic — pass the same value to both calls directly:
const ork = await getOrk({ topic: '<32-byte-hex>' })
const { manager } = await startWorker(WorkerClass, { orkTopic: '<32-byte-hex>' })The worker must join the topic before ORK starts listening. Start the worker process first, then start ORK. waitForDiscovery() polls the registry until discovered workers reach READY state.
The multi-process pattern is demonstrated end-to-end in dht-worker.js and dht-ork.js.
Next steps
- Operators: Configure how often ORK polls discovered workers: orchestrator cadences
- Operators: Diagnose startup hangs when outbound network is restricted: miner troubleshooting
- Integrators: see how workers register themselves on the DHT:
MDKWorkerAdapter