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 ORK, the Orchestration Kernel, distributed as @tetherto/mdk-ork.

MDK stack

The MDK components that compose those layers:

Storage

Hypercore-backed stores (such as Hyperbee) are recommended across the @tetherto/mdk-ork, Worker, and App Node 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-ork 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 over in-process calls, Holepunch RPC (HRPC), or API calls
• Strictly unidirectional: Workers never initiate RPC calls to @tetherto/mdk-ork; @tetherto/mdk-ork 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-ork, App Node, 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 ORK kernel

ORK, @tetherto/mdk-ork, 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-ork 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-ork, and the unyielding source of truth for that hardware: @tetherto/mdk-ork itself operates purely as a synchronized state machine over Worker-reported state.

Workers are passive — ORK initiates every RPC call; Workers only ever respond. ORK 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-ork 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 native transports (HRPC or IPC) seamlessly, offering:

• Transport abstraction: handles MDK Protocol message construction and reconnection logic with exponential backoff.
• Automatic transport selection: the SDK picks the transport mechanism based entirely on the URL scheme provided by the developer.
  • hrpc:// connects over encrypted Hyperswarm streams for remote server-to-server production.
  • ipc:// connects via direct local sockets for low-latency local testing.
• 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.

App Node

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

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 ORK connection — read the App Node concept page.

AI agents and the MCP server

AI agents connect to MDK through an MCP endpoint on the App Node, not directly to @tetherto/mdk-ork. By routing agents through the App Node, developers can keep them inside the same security envelope as every other consumer: they are ordinary authenticated clients; subject to the same JWT validation, rate limits, and RBAC as a human user. This is intentional: the 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 App Node.

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-ork instances. The kernel is only an execution layer; it does not perform application-level aggregation or cross-regional business logic.

how those processes are packaged on a host (one process vs many).

Parallel Workers

Multiple Workers of the same type (for example, whatsminer-worker) can be active concurrently and connected to the same @tetherto/mdk-ork 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-ork kernel, but all are overseen globally by a single App Node and AI Agent.

The single App Node and AI Agent connect globally to all distributed @tetherto/mdk-ork kernels via the native HRPC mesh (Hyperswarm). Parallel @tetherto/mdk-ork 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 App Node layer, where routes query multiple Workers via @tetherto/mdk-ork and merge the responses before returning them to the UI or Agent.

Next steps

Learn more about:

• About MDK
• MDK App Toolkit
• ORK
• Get started