Run a mining site end to end

Overview

This tutorial runs the full-site example end to end: multiple configured Workers across a range of device families, their mock device servers, a Gateway HTTP API, and a React dashboard, all from one command.

What you'll have at the end:

• The supported fleet: multiple miner types, container types, and power meters; one sensor family with two inlet sensors; and two mining pools, each backed by mock hardware that speaks the real wire protocol
• A Gateway API at :3007 serving /site/overview, /site/history, and /site/miners/:id/command
• A React dashboard at :3040 with live hashrate, power, and device status
• An MCP server at :3008 exposing the site's device registry, telemetry, and commands as tools for AI agents

The example boots either in one Node.js process (node start.js) or as separate supervised processes through an interactive REPL (node cli.js). This tutorial uses start.js, the shortest path, then shows the REPL as an optional step.

Prerequisites

• Node.js >=24 (LTS)
• npm >=11

git clone git@github.com:tetherto/mdk.git
cd mdk

cd examples/full-site
npm run setup

node start.js --miners 3

Gateway  http://localhost:3007
UI       http://localhost:3040

curl -s http://localhost:3007/site/overview | jq '{miners: (.miners|length), containers: (.containers|length), pools: (.pools|length), sensors: (.sensors|length)}'

{
  "miners": 9,
  "containers": 2,
  "pools": 2,
  "sensors": 2
}

node cli.js

up --miners 3
status
keys
ps

start worker whatsminer
logs gateway -f --grep site
seed whatsminer --container container-antspace
stop ui
down

What just happened

1. Setup installed backend/core, backend/workers, the MDK UI devkit, and this example, which are all the packages start.js imports at boot.
2. Mock hardware: mocks.js started one server per device family (miners on TCP, containers on HTTP and MQTT, power meters and sensors on Modbus, pools on REST). They speak the real wire protocols, so every Worker driver runs its true connect, collect, and command paths against them.
3. Kernel: getKernel() started the orchestration layer that discovers Workers as they register and routes telemetry pulls and commands to them.
4. Workers: eleven bootWorker() calls, one per configured Worker spec, each dispatching to that family's start{X}Worker() boot function (startWhatsminerWorker, startAvalonWorker, and so on) to construct a WorkerRuntime and connect it to the Kernel.
5. Gateway: startGateway() mounted the site plugin from plugins/site/ and opened the HTTP server on :3007. The plugin aggregates data across the configured Workers through mdkClient. The Gateway serves no routes of its own, so those three /site/* paths exist because this example mounts a plugin that provides them.
6. UI: a Vite React dev server started on :3040, serving a dashboard built from MDK devkit components.
7. MCP server: an MCP server started over HRPC on :3008, exposing the site's device registry, telemetry, and command dispatch as tools for AI agents.

Cleanup

Ctrl+C stops mocks, Workers, Kernel, Gateway, and the UI dev server cleanly. From the REPL, down or exit does the same.

State (Kernel key, Worker seeds, device registry, and tail-log history) persists in .mdk-data/. To wipe it:

rm -rf examples/full-site/.mdk-data

Next steps

• Build the same shape from an empty directory with one Worker and one route: build a minimal single-page dashboard
• Serve your own data by adding custom plugins to the Gateway HTTP API
• Integrate your own hardware by building a third-party Worker
• Run the same supported Worker fleet under PM2 or Docker with the multi-process deployment guide
• Browse every runnable example in one place