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 @mdk/ork.

MDK stack

The MDK components that compose those layers:

Storage

Hypercore-backed stores (such as Hyperbee) are recommended across the @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. Version 0.0.1 is pull-based: Workers passively join a known DHT topic and @mdk/ork initiates every RPC call. There are no Worker-to-kernel callbacks, no fan-out events, and no exceptions to the direction of flow. For the full envelope schema, action catalogue, and base command set, see the Protocol reference.

Design principles

• Transport-agnostic: identical messages over in-process calls, Holepunch RPC (HRPC), or API calls
• Strictly unidirectional: Workers never initiate RPC calls to @mdk/ork. They join a known Distributed Hash Table (DHT) topic; @mdk/ork discovers their presence passively 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 @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

@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.

Workers

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

Discovery model

1. DHT presence: the Worker joins a known Hyperswarm DHT topic. It does not send any RPC messages; it becomes a reachable peer.
2. Peer detection: @mdk/ork continuously listens on the same DHT topic and detects the new peer connection automatically.
3. Identity request: @mdk/ork initiates the first RPC call, requesting the Worker's identity and managed devices.
4. Registration: after receiving the identity, @mdk/ork saves the Worker and its RPC keys into its registry.
5. Capability declaration: @mdk/ork then explicitly queries the Worker to declare its full capabilities (mdk-contract.json).

Responsibilities and the capability contract

mdk-contract.json is the canonical source of truth for a Worker's programmatic capabilities and its AI context. MDK deliberately merges formal validation and semantic guidance into a single JSON contract:

• description does double duty as the human UI label and AI edge-case rule (for example, "Outlet temperature > 85C requires intervention")
• constraints governs orchestration limits
• troubleshooting provides if/then recovery behaviours alongside the payload it evaluates

The exhaustive JSON Schema is mdk-contract.schema.json, with a reference instance at mdk-contract.json.

Adding new hardware

External integrators add new hardware by building a Worker package that conforms to the strict Device-Lib Contract:

1. Reference mdk-contract.schema.json to author the mdk-contract.json, validating strict data schemas while injecting explanations, constraints, and troubleshooting directly into the relevant nodes.
2. Subclass @mdk/worker-base and implement the two translation hooks, onTelemetryPull and onCommand, in src/hardware.js. All HRPC plumbing is inherited from the base class.
3. Boot the Worker instance, connect to devices, and join the known DHT topic. @mdk/ork detects the peer and pulls its identity and capabilities.

The SDK

The @mdk/client SDK is the transport abstraction layer used to connect to @mdk/ork safely and 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 extremely low-latency local testing.
• Major language support: @mdk/client will be built for 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 is the developer-owned API boundary, the mandatory gateway between the client-facing world and @mdk/ork.

The UI never connects to @mdk/ork directly; an App Node must act as the gateway. Developers have two paths:

• Direct: write business logic, aggregation routes, and authentication directly in the App Node using @mdk/client in any language (Node.js, Go, Python, and others).
• Toolkit: adopt the MDK App Toolkit, which ships backend tools middleware (drops into Fastify or Express, handles JWT auth, RBAC, and command proxying), frontend tools, and a plugins shell for plug-and-play extensions.

Both approaches are fully supported; the choice depends on the team's preference for control versus convention.

Responsibilities

• Fleet aggregation: computes site hashrate, average temperature, cross-rack efficiency
• Auth and RBAC: guards all access to @mdk/ork with JWTs and session management
• API surface: exposes REST or GraphQL to the UI

Routing contract

UI and AI agents should only provide deviceId; the App Node (via @mdk/client) passes this down. @mdk/ork resolves the owning Worker internally and dispatches the command.request.

Authentication

The App Node validates a JWT (Bearer Token) (signature, expiry, claims) before proxying any traffic into @mdk/ork.

Allowlisting at the kernel: @mdk/ork does not perform user-level authentication. Instead, it maintains a strict allowlist of approved App Node and client connections. Once allowlisted securely (for example, via HRPC keys), @mdk/ork implicitly trusts the origin of HRPC messages.

AI agents and the MCP Server

AI agents connect to MDK through an MCP endpoint on the App Node, not directly to @mdk/ork. They are treated as ordinary authenticated clients and 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, so routing agents through the App Node keeps them inside the same security envelope as every other consumer.

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 @mdk/ork instances. The kernel is strictly 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 @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 @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 @mdk/ork kernels via the native HRPC mesh (Hyperswarm). Parallel @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 @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