Architecture

How MDK works

MDK is built around a small kernel with one job: route validated commands to whichever Worker owns a device, and pull telemetry back. Everything else (authentication, business logic, UI, AI agents) sits outside the kernel as composable layers: keeping the kernel small and the application surface open.

To prevent unbound flexibility from manifesting as system rigidity, the architecture draws a hard line between what is standardized and what is delegated. It's:

• Opinionated where needed: strict transport envelopes, unified JSON schema, unidirectional flows
• Flexible where it matters: isolated Workers handle translation logic, enabling integrations without polluting the core infrastructure

Five layers compose the stack, with strict, unidirectional flows between them. The kernel itself is Kernel, the Orchestration Kernel, distributed as @tetherto/mdk-kernel.

MDK stack

The MDK components that compose those layers:

Storage

Hypercore-backed stores (such as Hyperbee) are recommended across the @tetherto/mdk-kernel, Worker, and Gateway layers. This choice satisfies all storage requirements without the operational baggage of a centralized database.

The MDK protocol

The MDK protocol is the contract that crosses every layer of the stack. Workers become reachable — via a DHT topic or same-machine discovery, and @tetherto/mdk-kernel initiates every RPC call. Workers issue no callbacks, emit no fan-out events, and make no exceptions to the direction of flow.

Design principles

• Transport-agnostic: identical messages whether routed in-process, over Hyperswarm RPC (HRPC), or via API calls
• Strictly unidirectional: Workers never initiate RPC calls to @tetherto/mdk-kernel; @tetherto/mdk-kernel discovers their presence and initiates all subsequent communication downwards (identity, capabilities, telemetry, commands)
• Generic interface: the accepted interface is defined dynamically at the Worker level via a self-describing capabilities schema containing both structure and semantic context for AI agents

Governance

To maintain structural integrity and contract stability across @tetherto/mdk-kernel, Gateway, and Workers, MDK protocol messages are governed and strictly validated using Hyperschema. Hyperschema also aligns natively with the system's underlying Hyperbee storage.

Discovery, telemetry, and command flows

The Kernel

Kernel, @tetherto/mdk-kernel, is the trusted coordination layer at the heart of MDK. It routes commands, monitors device health, registers Workers, and pulls telemetry — all on a pull-only model, so the kernel cannot be overwhelmed by upstream pressure.

When a command arrives, callers only need to provide a deviceId; @tetherto/mdk-kernel resolves the owning Worker internally via the CommandDispatcher and dispatches the command.request.

Workers

Workers wrap a device library and expose it via the MDK protocol. They are the integration handlers between physical hardware and @tetherto/mdk-kernel, and the unyielding source of truth for that hardware: @tetherto/mdk-kernel itself operates purely as a synchronized state machine over Worker-reported state.

Workers are passive — Kernel initiates every RPC call; Workers only ever respond. Kernel discovers Workers according to the discovery model, then requests identity and capabilities.

The SDK

The @tetherto/mdk-client SDK is the transport abstraction layer used to connect to @tetherto/mdk-kernel reliably. It is the essential glue between the kernel and any consumer layer developers choose to build on top.

Responsibility: connects the MDK Protocol over the native HRPC transport seamlessly, offering:

• Transport abstraction: handles MDK Protocol message construction and reconnection logic with exponential backoff.
• Key-based addressing: the SDK connects over encrypted Hyperswarm streams, addressed by the kernel's HRPC public key. The same transport serves remote server-to-server production and same-host development alike — for the local zero-config case, the kernel publishes its key to a well-known key file that clients read at startup.
• Major language support: @tetherto/mdk-client is intended to support all major languages (Node.js, Python, Go, and others), allowing developers to dispatch commands, subscribe to live streams, or pull status snapshots from any stack.

Gateway

The Gateway wraps @tetherto/mdk-client — the MDK protocol connector to Kernel — to add an authenticated HTTP, WebSocket, and MCP interface on top. Consumers that need those capabilities connect through the Gateway.

The supported development path is the MDK App Toolkit, which ships backend middleware (JWT auth, RBAC, and command proxying), frontend tools, and an mdk-plugin.json-based plugin system for declarative HTTP route extensions (plugin guide).

For the full developer model — extension patterns, data access, auth design, and Kernel connection — read the Gateway concept page.

AI agents and the MCP server

The supported application path connects AI agents through an MCP endpoint on the Gateway. This keeps agents inside the same security envelope as other consumers: they are authenticated clients subject to the same JWT validation, rate limits, and RBAC as a human user. This is intentional because Kernel does not perform user-level authentication.

What makes the integration distinctive is runtime tool derivation. The tools exposed to an agent (for example, get_device_telemetry or reboot_device) are not hardcoded; they are parsed at runtime from each registered Worker's mdk-contract.json. When a new device type joins the network, the agent gains the ability to query and control it without any change to the Gateway.

End-to-end data flows

Two scenarios show the full request path from consumer to device and back: a human user clicking through the UI, and an AI agent executing a multi-step prompt.

AI agent scenario

A user instructs the AI Agent: "Keep the fleet healthy." The agent monitors continuously, catches wm002 overheating, reboots it, and notifies the user.

Human UI scenario

A user clicks "Reboot" on device wm001 in the UI.

Scaling

As MDK deployments scale to large mining sites (5,000+ devices), the system must explicitly manage parallel Workers and parallel @tetherto/mdk-kernel instances. The kernel is only an execution layer; it does not perform application-level aggregation or cross-regional business logic.

Parallel Workers

Multiple Workers of the same type (for example, whatsminer-worker) can be active concurrently and connected to the same @tetherto/mdk-kernel kernel.

Device-level routing and ownership: Workers never share devices. When a Worker connects, its identity.register payload explicitly lists the deviceIds it exclusively manages. The Worker registry maintains this strict mapping and deterministically routes arriving commands to the designated Worker.

Multi-site deployments

A deployment may need to manage multiple massive physical boundaries (for example, a Texas Site and an Iceland Site). Each location runs its own dedicated site-level @tetherto/mdk-kernel kernel, but all are overseen globally by a single Gateway and AI Agent.

The single Gateway and AI Agent connect globally to all distributed @tetherto/mdk-kernel kernels via the native HRPC mesh (Hyperswarm). Parallel @tetherto/mdk-kernel instances remain entirely isolated from one another: they do not federate registries, share queues, or synchronize state. A crash at one site has zero impact on any other.

Cross-site aggregation is handled purely at the Gateway layer, where routes query multiple Workers via @tetherto/mdk-kernel and merge the responses before returning them to the UI or Agent.

Next steps

• Understand the Kernel — what it owns, the pull-only model, and transports
• Understand the Gateway — authentication, RBAC, plugins, and Kernel connection
• Understand Workers — discovery model, capability contract, and adding hardware
• Understand the control plane — how Gateway, Kernel, and Workers communicate and which layer owns each responsibility
• Choose a deployment topology — single-process, local, or distributed

Next steps

Learn more about:

• About MDK
• MDK App Toolkit
• Kernel
• Get started