Architecture

How MDK works

MDK is built around a three tier ownership model:

• Kernel is invariant The Kernel provides small coordination layer every deployment runs unchanged: it routes validated commands to whichever Worker owns a device, and pulls telemetry back.
• Extensions are yours Worker plugins wrap a device family; Gateway plugins add HTTP routes, aggregation, and auth. Both are code you write and own, isolated from the Kernel and from each other. Nothing above the Gateway is required: a deployment can dispatch commands and pull telemetry with just @tetherto/mdk-client.
• The UI devkit is optional The MDK App Toolkit is the supported path for teams that want one.

The round trip

One request, traced end to end: an AI agent or a dashboard reaches a Gateway plugin's capability. A dashboard calls the plugin's HTTP route directly; an AI agent arrives instead through an MCP endpoint — a standalone @tetherto/mdk-mcp process that derives tools from that plugin's routes (the Gateway doesn't host the MCP itself). Either way the plugin builds its own @tetherto/mdk-client and dispatches a command through it. Kernel resolves which Worker owns the target device, forwards the command over the Worker's own connection, and relays the result back through the same path: Gateway plugin, then caller. Telemetry travels the same round trip in reverse, on demand: the Gateway plugin's client asks Kernel for a device's telemetry, Kernel forwards that pull to the owning Worker and relays the answer straight back. Kernel also runs its own scheduled telemetry/health pulls on a fixed cadence, independent of any caller: the two are separate triggers into the same path, not one waiting on the other.

Both extension points sit at the edges of this trip, never in the middle: a Worker contract teaches Kernel about one device family (the contract declares the capability surface; the plugin's handlers implement it), and a Gateway plugin teaches the Gateway a new route. Kernel itself never changes.

The three tiers

Gateway: a container that hosts plugins and exposes them over HTTP. It is the active side of the Kernel connection (it dials Kernel, never the reverse). This is the tier where user-level authentication, aggregation, and business logic live. Aggregation here means the cross-Worker queries no single Worker can answer — site hashrate, average temperature, cross-rack efficiency — resolved in controller code, since Kernel computes none of them. Kernel's own allowlist, when configured, gates which connections it accepts: a transport-level check, not a user identity.

Workers: the integration handlers between physical hardware and Kernel, and the source of truth for that hardware's state. A Worker answers only when Kernel asks (identity, capabilities, telemetry, or a command) and never calls Kernel unprompted.

Kernel: the passive coordination layer. It never initiates contact with a caller; it discovers Workers, routes commands to the one that owns a device, and pulls telemetry and health on its own cadence. It performs no aggregation and stores no telemetry itself.

How Kernel communicates with a Worker

Suppose Kernel needs a temperature reading from a Worker's device. Four separate questions explain how that telemetry reaches Kernel:

1. Discovery: Which Worker should Kernel contact? Kernel learns the Worker's public key, which identifies the Worker.
2. Connection: How can Kernel reach that Worker? HyperDHT helps locate and establish a connection to the peer (Worker) identified by that key.
3. Permission: Does the Worker allow Kernel to call it? The Worker checks the caller's key against its allowlist.
4. Request: What does Kernel want the Worker to do? Kernel sends a telemetry pull (in our scenario, the temperature reading request) over HRPC, and the Worker replies.

Knowing a public key does not by itself grant a connection or permission to call; the allowlist check happens when connections are established and requests are handled.

Why HRPC?

Gateway to Kernel and Kernel to Worker communications use Hyperswarm RPC (HRPC) to connect known backend peers through the same encrypted, public-key-addressed interface, irrespective of whether they run together or on separate hosts. This suits a site's backend communication: callers identify peers by key instead of addressing public HTTP endpoints.

What's authoritative vs. cached

Kernel's own store holds only its Worker registry, device capabilities, and the write-command log: never telemetry. Telemetry is Worker-owned: a Worker persists its own device history, and every telemetry read anywhere above it (Gateway plugin, dashboard, agent) is a live pull through that chain, not a read from a Kernel-side cache.

The stack

Discover each layer's canonical docs:

For the per-package detail in each workspace, read the core package index and the UI toolkit index. How many of each a deployment runs is covered by scalability.

Next steps

• Understand the integration model: what a Worker plugin and a Gateway plugin each get to do
• Understand the storage model: where state actually lives as you scale
• Understand the security boundaries: what each tier does and does not authenticate, and what you must build
• Understand what an app is in MDK terms
• Understand scalability: parallel Workers, parallel Kernels, and what's measured today
• Understand the MDK App Toolkit: the recommended development path from Gateway backend to frontend packages
• Connect an AI agent over MCP: the endpoint agents reach the fleet through, and the security envelope you supply