About MDK

Introducing MDK

MDK, the Mining Development Kit, is an open-source platform that delivers a modern, transparent, and modular infrastructure for Bitcoin mining operations. MDK enables Bitcoin mining operations to start small, scale smoothly, and remain in full control, without lock-in, rewrites, or hidden complexity.

The problem

The Bitcoin mining industry has long been constrained by closed systems, proprietary tooling, and vendor lock-in. MDK changes that.

The solution

MDK delivers a modular mining stack that empowers operators and developers to build, monitor, control, and scale mining operations with full ownership: from a single device to gigawatt-scale facilities — without architectural rewrites.

MDK ships three conceptual layers, each containing one or more packages:

1. Orchestration kernel (Kernel).
2. Universal SDK.
3. MDK App Toolkit.

All three communicate through the MDK protocol. Clients — browsers and AI agents alike — reach the kernel exclusively through the Gateway, the consumer-facing integration boundary your team builds with the SDK. MDK ships no authentication of its own at any tier: your team supplies it in the Gateway plugin controllers you write. Tying everything together is a single contract per device type: the same mdk-contract.json is designed to serve the UI (data labels), the orchestrator (validation rules), and AI agents (reasoning context) — today, only the orchestrator's validation rules are actually wired to it; UI and agent tooling don't read it yet. One file, one intended source of truth for three audiences.lea

The orchestration kernel

Kernel, the Orchestration Kernel, is distributed as @tetherto/mdk-kernel. It's the central coordination engine of MDK and serves as a controller: it knows which devices are online, routes commands to the right place, monitors health, and collects performance data.

@tetherto/mdk-kernel communicates with Workers, never devices directly, through a standardized language called the MDK Protocol, a common set of messages every Worker in the system understands, regardless of the device manufacturer or model behind it. Adding a new device type never impacts @tetherto/mdk-kernel thanks to the Worker, a device-specific translator that sits between the kernel and your hardware: it speaks the MDK Protocol upward, and the device's native API downward.

The kernel is pull-only, device-agnostic, and self-healing.

Learn more about the internal modules, recovery flows, and protocol specs that back those guarantees.

The universal SDK

@tetherto/mdk-client is the universal SDK, a connection library that applications use to talk to @tetherto/mdk-kernel. It serves as a universal adapter: handling all the connection details so developers can focus on building their application.

• Node.js today: @tetherto/mdk-client ships as a Node.js package. The transport and protocol are designed to allow future clients in other languages (Python, Go, and others) without changes to Kernel or the protocol itself
• Automatic connection handling: manages reconnection, retries, and transport selection behind the scenes
• No lock-in: developers bring their own stack and connect via the SDK. No framework requirements.

MDK App toolkit

For teams that want to ship fast, the MDK App Toolkit is the optional, batteries-included application layer that sits on top of @tetherto/mdk-kernel. It ships in three parts:

• Frontend tools: a headless state brain (@tetherto/mdk-ui-foundation), framework adapters (@tetherto/mdk-react-adapter for React today), and a production-tested React UI Kit (@tetherto/mdk-react-devkit) for dashboards.
• Backend tools: the Gateway itself, a Fastify-specific library handling command proxying and request-level caching, with hooks for custom routes and aggregations. There is no Express adapter today.
• Plugins: a Gateway plugin's mdk-plugin.json declares its own routes; pairing one with a specific frontend tools widget is application code you write, not a manifest mechanism the Toolkit provides for you today. Third parties can ship whole features without forking the Gateway.

Using @tetherto/mdk-client without the Gateway is technically possible but not supported by this monorepo — most applications build on the Gateway.

Who MDK is for

MDK is built for everyone involved in mining Bitcoin:

• Mining operators: monitor and control fleets with real-time dashboards. Get fleet-wide summaries (total hashrate, power usage, temperature alerts) across all your sites.
• Hardware manufacturers: integrate new devices by building a Worker and writing one mdk-contract.json. No involvement from MDK maintainers needed.
• Software developers: build custom mining applications in any language, or leverage the MDK App Toolkit's frontend and backend tools for rapid development.
• AI/Automation teams: connect intelligent agents that can monitor and diagnose device issues autonomously, then act on them once an operator approves the write

Architecture overview

@tetherto/mdk-kernel is the kernel. @tetherto/mdk-client is the protocol connector every caller uses to reach it. Above those two layers, the supported development path builds in two levels:

• Gateway: the Gateway hosts plugins and adds request-level caching and an HTTP interface; each plugin builds its own @tetherto/mdk-client and does its own fleet aggregation. Authenticating callers is left to the plugin controllers you write. AI agents can drive the fleet over MCP — a standalone @tetherto/mdk-mcp process, or one the Gateway auto-generates in-process from a plugin's routes
• MDK App Toolkit: sits on top of the Gateway. Adds a plugin system for declarative route extensions and frontend packages (@tetherto/mdk-ui-foundation, React adapter, React UI kit) for teams building operator dashboards

Below the kernel, devices are the source of truth. The actual hardware state is reported by the Worker to @tetherto/mdk-kernel, which orchestrates a synchronized view across the fleet.

For the full layer-by-layer view with transports and discovery flows, see the MDK stack on the Architecture page.

AI-ready with unified intelligence

MDK is designed from the ground up for AI-driven operations. Rather than bolting AI on as an afterthought, intelligence is woven directly into the device definition itself.

In addition to the technical schemas, every device's contract file (mdk-contract.json) contains:

• Safety rules: for example, "Outlet temperature > 85°C requires immediate intervention"
• Operational constraints: limits on command frequency, power thresholds, cooling requirements
• Troubleshooting guides: if/then recovery steps an AI agent can diagnose against autonomously; the recovery action itself still waits for operator approval, the same as any other write

The intent is that an AI agent connecting to MDK wouldn't need a separate knowledge base or custom prompts per device: the same contract that Kernel already validates commands against would also determine how AI reasons about that hardware. That wiring is not built yet: MCP tools today come from a separate, hand-authored manifest, not from a Worker's contract (see Connecting intelligent agents).

What you can build

• Operational dashboards (hashrate, power, temperature)
• Multisite fleet management with centralized oversight
• Alerts and notifications for critical device events
• Overheating detection and automated remediation
• AI-driven autonomous monitoring, with human-approved control actions
• Custom analytics and reporting pipelines
• White-labeled hosted mining platforms
• Third-party device integrations and plugins

Scaling

MDK scales naturally without architectural changes:

• More devices? Add more Workers. Each Worker owns a specific set of devices, and @tetherto/mdk-kernel routes commands to the right one automatically.
• More sites? Each physical site runs its own @tetherto/mdk-kernel instance, each behind its own Gateway. A single Gateway aggregating every site into one view is on the roadmap; today, that view is your own application code calling each site's Gateway and merging the results.
• Site isolation: @tetherto/mdk-kernel instances are fully independent. A problem at one site has zero impact on any other.

Next steps

Learn more about:

• Architecture
• MDK App Toolkit
• Connecting intelligent agents