About MDK
Open, modular infrastructure for Bitcoin mining at any scale
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:
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-clientships 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-adapterfor 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.jsondeclares 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-clientand 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-mcpprocess, 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-kernelroutes commands to the right one automatically. - More sites? Each physical site runs its own
@tetherto/mdk-kernelinstance, 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-kernelinstances are fully independent. A problem at one site has zero impact on any other.
Next steps
Learn more about: