Glossary
Learn the MDK vocabulary for Kernel, Gateway, Workers, managers, things, and mocks
This page provides explanations for terms that new users may not be familiar with.
Stack and hardware terms
This section explains the terms you need to familiarize yourself with, using an Antminer rack as an example.
| Term | What it is | Lives at |
|---|---|---|
| Kernel (Orchestration Kernel) | The pull-only kernel that owns the device registry, routes commands, and pulls telemetry on its own cadence — it performs no aggregation itself | backend/core/kernel/ |
| Gateway | The developer-owned entry point between non-Node clients (UI, AI agents) and Kernel. Mandatory whenever a non-Node consumer reaches the kernel; not used in the in-process Antminer-rack example below | backend/core/gateway/ |
| Worker | A device-family translator. Speaks the MDK Protocol upward to Kernel and the vendor's native API downward to one device family (one miner brand, one container type, one pool API). | backend/workers/ |
| Driver class | The JavaScript class a Worker exports, one per device family (for example Antminer, Whatsminer), not one per model. Drives every device that Worker registers. | backend/workers/miners/antminer/lib/antminer.js |
| Thing | One registered device instance. Created by sending a registerThing command to the Worker's provisioning service, not by calling a driver-class method directly. Identified by a generated deviceId. | backend/core/mdk/lib/services/provisioning.service.js |
| MCP (Model Context Protocol) | The protocol AI agents use to discover and call tools. @tetherto/mdk-mcp runs either as its own standalone process, or in-process inside the Gateway when a plugin's routes are auto-generated into tools | backend/core/mcp/ |
How they compose, for an Antminer rack
The same shape repeats for every other device family (Whatsminer, container vendors, pool APIs). Scalability covers the multi-Worker view, parallel Workers, and multi-site deployments.
Hyperswarm RPC
MDK uses @hyperswarm/rpc as its runtime transport. Hyperswarm RPC (HRPC) is not an HTTP-based RPC system. It is an RPC layer
that rides on Hyperswarm peer-to-peer connectivity. The library is a simple RPC over the Hyperswarm DHT, backed by Protomux. Think of it as a peer-to-peer
remote function call system built on a DHT and an encrypted connection layer.
Mental model — Hyperswarm finds peers and establishes connections; Protomux divides the connection into named channels;
RPC defines the conversation — a caller names a method and receives a reply.
A useful analogy is a phone call between peers — Hyperswarm helps the phones find each other and connect; Protomux splits
the line into channels; RPC defines how one side asks for a method and the other side responds.
Practical implications:
- You work with services, methods, requests, and responses — not URLs and routes
- The RPC-shaped API is identical across same-process, same-host, and distributed deployments; only the discovery mechanism changes (same-process registration, shared directory, or DHT topic)
- Peers discover and communicate without a central HTTP server
HRPC on the same host
MDK uses HRPC as the single transport across all deployment shapes — same-process, same-host, and distributed. Every component is addressed by its public key, not by a socket path or hostname. The Gateway, a standalone Node.js script, and a remote service all connect the same way:
createMdkClient({ kernelKey: key })The Noise handshake that HRPC performs on every connection authenticates by key, so Kernel's allowlist works identically whether the caller is on the same machine or a remote host.
This is consistent with the broader Holepunch ecosystem philosophy — everything is a peer addressed by public key. When the peer is on the same machine it routes locally over the local network interface; the application code sees no difference.
Next steps
- You are ready to run the example in Run a mining site end to end
- Learn more about:
- Multi-process discovery across machines: Worker discovery
- Gateway implementation details, including HTTP routing and plugin registration:
backend/core/gateway/README.md - Building your own Worker for a new device family: see the build walkthrough
- The install and run pattern every shipped Worker package follows:
backend/workers/docs/install-pattern.md - Per-device contract details (telemetry units, command shapes, error codes): those live in each Worker's
mdk-contract.json, e.g.backend/workers/miners/antminer/plugin/mdk-contract.json