Run a mining site end to end

Install the example

1.1 Clone the repo

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

1.2 Run setup

cd examples/mvp-site
npm run setup

setup first copies the committed *.json.example config files into place without overwriting any that already exist (the same step npm run setup:config runs on its own), then installs backend/core, backend/workers, the UI workspace devkit packages, and this example's own dependencies.

Start the site

npm start

start.js generates deploy/ecosystem.config.js from config/site.deploy.json, starts the PM2 apps, then exits — PM2 itself keeps the processes running in the background.

pm2 list      # dht-bootstrap, mocks, mocks-antminer, mocks-sealminer, mocks-ocean, mocks-satec, mocks-emcd, mocks-spiderpool, mocks-foundry, kernel, worker, worker-antminer, worker-sealminer, worker-ocean, worker-satec, worker-emcd, worker-spiderpool, worker-foundry, app-site, gateway, mcp

Wait for every app to show online, then open http://localhost:3000/ in a browser and sign in as one of the example's demo users. The dashboard shows live hashrate, power, and per-device status.

Verify via the API. App routes need a signed-in user, so sign in first and send the access token. viewer is the read-only demo user; any of the others works too.

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)}'

Expected output:

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

Once the Kernel marks a Worker DEAD or TERMINATED, its miners are missing from miners and the overview lists it in unavailableWorkers with that state, for example { "workerId": "whatsminer-worker", "reason": "DEAD" }, so an outage doesn't read as an empty site. Each of its devices you may read is listed in unavailableDevices with status: "offline" and stale: true, and totals.unavailableDeviceCount counts them. Before that, while the Kernel only reports the Worker SICK, its miners can drop out of miners without an unavailableWorkers entry. A command the Kernel refuses, such as one for a device that doesn't exist, answers 404 for an unknown device or Worker and 422 otherwise, with the Kernel's error code in the body.

(Optional) Explore the UI pages

The Dashboard, Containers, Miners, Power & Sensors, Pools, Control, and Activity pages are all served from ui/dist via the Gateway on the same :3000 port. The Pools page lists the Ocean, EMCD, SpiderPool, and Foundry accounts side by side; the Power & Sensors page charts the SATEC meter's power series over time. UI pages describes what each one shows.

(Optional) Report a real EMCD, SpiderPool, or Foundry account

The EMCD, SpiderPool, and Foundry Workers read their API credentials from the environment, never from config/site.deploy.json. With the variables unset, each Worker logs a warning and authenticates with its package's public mock credentials, which only the bundled mock accepts.

To switch one pool to the live API, set its variables in the shell you run npm start from, then in config/site.deploy.json remove that pool's pool.apiUrl so the Worker uses its package default, set pool.accounts, and remove its mocks-emcd, mocks-spiderpool, or mocks-foundry entry from pm2.roles. Run npm run stop:pm2 and npm start to apply it. The pool config reference covers every setting.

Ask a coding agent about the fleet

The mcp process started in step 2 serves the site as tools on :3101. It is the same standalone server that mdk run mcp starts for a project scaffolded with the CLI; here the example launches it as a PM2 process.

Connect your coding agent to the server. .mcp.json.example holds the entry. For an agent that reads a project-level .mcp.json (such as Claude Code), copy it and start the agent from the example directory:

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

Accept the mdk-site-agent-tools server if prompted, then confirm it shows as connected.

For any other MCP client, add http://127.0.0.1:3101/mcp as an HTTP server in its MCP settings.

Ask these three questions in order:

The wording and figures may vary slightly depending on your model and mock seeds, but your agent should call these tools and report figures like those in the table. The mock miners of one model report the same readings, so ties in the ranking are expected.

The server carries two tool sources:

• A hand-authored tool set with agent-contract metadata (backend/mcp-plugins/site/mcp-plugin.json) giving an agent summary-first, closed-vocabulary tools (summarize_site, count_devices, list_devices, get_device, rank_devices) instead of raw route exports
• The site app's own /site/* routes, read off the same route table the Gateway forwards and converted into tools

Point an MCP client at that URL and it can query the fleet. The MCP server itself has no approval step: once write tools are enabled, a call runs as soon as the client sends it, and only the operator agent adds a human approval. This local site admits its own processes through the trusted-keys directory on this machine; a hardened Kernel restricts the MCP connection through Kernel's caller allowlist.

Stop the site

npm run stop:pm2

This stops and removes every PM2-managed process for this site: the private DHT bootstrap, mocks, Workers, Kernel, the site app, Gateway, and the MCP server.