Run a mining site end to end

Overview

This tutorial runs the Starter site example end to end: a Whatsminer worker, an Ocean pool worker, and a SATEC powermeter worker, each backed by mock hardware that speaks the real wire protocol, a Gateway HTTP API, and a React dashboard, all supervised by PM2.

What you'll have at the end:

• Mock miners, a mock pool, and a mock powermeter, each driven by the real Worker driver code against a localhost mock instead of hardware
• A Gateway API on :3000 serving /site/overview, /site/history, /site/miners/:id/command, and /site/miners/:id/pools
• A React dashboard on :3000 with Dashboard, Containers, Monitoring, Pools, and Control pages
• Two MCP surfaces exposing the site as tools for AI agents: the Gateway's auto-exported routes on :3100, and a hand-authored, agent-contract tool set on :3101

Every component above runs as its own PM2-supervised OS process, discovering the Kernel over a shared local directory rather than a DHT.

Prerequisites

• Node.js >=24 (LTS)
• npm >=11
• PM2 (npm install -g pm2)

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

cd examples/mvp-site
npm run setup
npm run setup:config

npm start

pm2 list      # mocks, mocks-ocean, mocks-satec, kernel, worker, worker-ocean, worker-satec, gateway, mcp

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

{
  "miners": 5,
  "pools": 1,
  "powermeters": 1
}

npm run stop:pm2

What just happened

1. Setup installed backend/core, backend/workers, the MDK UI devkit, and this example, then setup:config seeded its local config from the committed *.example files.
2. Mock hardware: PM2's mocks, mocks-ocean, and mocks-satec roles each started a mock device server — a Whatsminer miner, an Ocean pool, and a SATEC powermeter — speaking the real wire protocol, so the Worker drivers run their true connect, collect, and command paths against them.
3. Kernel: the kernel role started the orchestration layer in local-discovery mode, watching a shared directory for Workers to publish their RPC keys to.
4. Workers: the worker, worker-ocean, and worker-satec roles each dispatched to that family's boot function (startWhatsminerWorker, startOceanPoolWorker, startSatecWorker) to construct a WorkerRuntime, seed its devices from config/devices.json, and publish its RPC key for the Kernel to discover.
5. Gateway: the gateway role mounted the site plugin declared by backend/gateway-plugins/site/mdk-plugin.json and the built UI from ui/dist, then opened the HTTP server on :3000. The plugin aggregates data across the three Workers through mdkClient.
6. MCP: the mcp role started both MCP surfaces — the Gateway's auto-exported tools on :3100, and the hand-authored agent-contract tool set on :3101.

Resetting state

State (Kernel key, Worker seeds, device registry) persists in .site-data/. If you change config/devices.json after the first run, reset it before restarting — seed devices are only registered once, on an empty store.

Next steps

• Fix a failed boot, a port clash, or stale PM2 processes with the example's troubleshooting section
• Register real hardware instead of mocks by configuring devices
• 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 PM2-supervised model as a production deployment, or across hosts with DHT discovery, with the supervised-services deployment guide
• Go beyond querying the site's MCP tools by hand: connect the conversational operator agent, which calls the same tools and gates writes behind human approval
• See the full 11-worker fleet — three miner families, containers, sensors, and two pools — in examples/full-site
• Browse every runnable example in one place