Run a mining site end to end

Overview

This tutorial runs the Starter site example end to end: Whatsminer, Antminer, and SealMiner Workers, Ocean, EMCD, SpiderPool, and Foundry pool Workers, and a SATEC powermeter Worker, each backed by a mock that speaks the real wire protocol, plus a Gateway HTTP API and a React dashboard, all supervised by PM2.

What you'll have at the end:

• Mock miners, four mock pool APIs, 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
• One MCP surface on :3101 exposing the site as tools for AI agents, served by a standalone MCP process: a hand-authored, agent-contract tool set alongside the site app's own routes, read off the same route table the Gateway forwards

Every component above runs as its own PM2-supervised OS process. Kernel discovers the Workers through a shared local directory rather than a DHT topic, and the Gateway and MCP server find Kernel through its well-known key file.

Prerequisites

• Node.js >=24 (LTS)
• npm 11 (< 12)
• PM2 (npm install -g pm2)
• Outbound UDP to the HyperDHT bootstrap nodes

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-antminer, mocks-ocean, mocks-satec, mocks-emcd, mocks-spiderpool, mocks-foundry, kernel, worker, worker-antminer, worker-ocean, worker-satec, worker-emcd, worker-spiderpool, worker-foundry, app-site, gateway, mcp

TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"viewer","password":"mdk-site-demo"}' | jq -er .accessToken)

curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/site/overview | jq '{miners: (.miners|length), pools: (.pools|length), powermeters: (.powermeters|length)}'

{
  "miners": 10,
  "pools": 4,
  "powermeters": 1
}

cd examples/mvp-site
cp .mcp.json.example .mcp.json
claude

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-antminer, mocks-ocean, mocks-emcd, mocks-spiderpool, mocks-foundry, and mocks-satec roles each started a mock server (Whatsminer and Antminer miners, the Ocean, EMCD, SpiderPool, and Foundry pool APIs, 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-antminer, worker-ocean, worker-emcd, worker-spiderpool, worker-foundry, and worker-satec roles each dispatched to that family's boot function to construct a WorkerRuntime and publish its RPC key for the Kernel to discover. The miner and powermeter Workers seed their devices from config/devices.json. Each pool Worker is one logical device that polls its pool's API. The EMCD and SpiderPool Workers come from external git packages, booted by backend/pool-adapter.js.
5. App and Gateway: the app-site role ran the site app (backend/gateway-plugins/site) in its own app runtime, and the gateway role mounted that app's routes at / and the built UI from ui/dist, then opened the HTTP server on :3000, forwarding each /site/* request to the app. The app aggregates data across the six Workers through mdkClient.
6. MCP: the mcp role started the standalone MCP process on :3101, serving both tool sources — the hand-authored agent-contract tool set and the site app's own routes, derived from the same route table the Gateway forwards.

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
• Browse every runnable example in one place