Build your first app with a UI

Overview

This quickstart takes a clean machine with Node.js to a running MDK project of your own, using only the mdk CLI: one Worker reading a mock miner, one app with its own HTTP route and React page, and the MDK dashboard that loads that page. You write no code until the last step, where you change the starter page and see it update.

What you'll have at the end:

• A Worker, rig, reading a mock miner that speaks the real wire protocol
• An app, ops, serving GET /apps/ops/api/ops/summary through the Gateway, with a starter page built from MDK UI components
• The MDK dashboard at http://localhost:3030, showing the app's page and its card on Home

The project lives outside the MDK checkout:

my-site/
├── mdk.yaml              # the stack spec: Kernel, Gateway, Workers, apps
├── package.json          # links workers/ and apps/<name>/ by file: dependencies
├── workers/
│   └── rig/              # the Worker: contract, handlers, mock device
├── apps/
│   ├── ops/              # the app: route table, controllers, ui-src/ and the built ui/
│   └── dashboard/        # the MDK dashboard (UI shell)
└── .mdk/                 # runtime state written by `mdk run`, disposable

Prerequisites

• Node.js >=24
• npm 11 (below 12)
• git
• jq, to read the access token out of the sign-in response
• macOS or Linux, with a bash or zsh shell
• About 2 GB of free disk space
• Ports 3847 (Gateway), 3848 (Kernel) and 3030 (dashboard) free. mdk run fails if the Gateway or Kernel port is taken, so stop any stack still running from an earlier demo first. The dashboard moves to another port on its own.

Time

These are command times from a fresh clone with an empty npm cache, so every package is downloaded, measured on an Apple M1 Pro with a fast connection. A slower machine or network takes several times longer and still fits in 15 minutes with time to read each step. A second project skips the first part.

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

npm ci                                # the backend packages and the CLI
npm --prefix ui ci                    # the UI packages
npm run build:ui                      # build them: the dashboard and app UIs link to the built output
npm run build -w @tetherto/mdk-cli    # build the CLI
npm rebuild @tetherto/mdk-cli         # link the `mdk` command, now that it is built
export PATH="$PWD/node_modules/.bin:$PATH"
mdk --version

mkdir ~/my-site && cd ~/my-site
cat > mdk.yaml <<'YAML'
apiVersion: mdk/v1
kind: Stack
metadata:
  name: my-site
spec:
  kernel: { port: 3848 }
  gateway: { port: 3847 }
  workers: []
  apps: []
YAML

mdk create worker rig

mdk create app ops

✔ Scaffolded app ops → /home/you/my-site/apps/ops
  package ops
  ✔ Built the starter UI → ui/index.js (source in ui-src/)
  ✔ Added to mdk.yaml under spec.apps

mdk create dashboard

mdk rbac init
mdk run

✔ gateway listening on http://localhost:3847

Stack running. Press Ctrl+C to stop.

mdk user add admin --admin   # prompts for a password

mdk run dashboard

TOKEN=$(curl -s -X POST http://localhost:3847/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"admin","password":"<the password you set>"}' | jq -er .accessToken)

curl -s -H "Authorization: Bearer $TOKEN" http://localhost:3847/apps/ops/api/ops/summary

{"ok":true,"kernelConnected":true,"workerCount":1,"deviceCount":1,"workers":[{"workerId":"rig","devices":1}]}

cd ~/my-site/apps/ops
npm run build:ui

What just happened

1. mdk.yaml is the stack spec. Each mdk create command added its component to it, and mdk run boots what it lists.
2. The Worker runs its mock miner (mock: true in mdk.yaml) and registers its device with the Kernel.
3. The app declares its routes in apps/ops/plugin/mdk-plugin.json. Its summary controller asks the Kernel which Workers and devices are connected.
4. The Gateway signs users in at /auth/login, checks every call against the spec.rbac rules bound to the signed-in user, serves the app's routes under /apps/ops/, and forwards each allowed call to the app.
5. The dashboard serves the app's built UI from apps/ops/ui/, and its dev server proxies /apps/* to the Gateway, so the page fetches from the same origin.

Cleanup

Press Ctrl+C in both terminals. mdk run stops every component it started.

To reset the stack's state, delete ~/my-site/.mdk/. To remove the project, delete ~/my-site/.

Next steps

• Add your own route: extend apps/ops/plugin/ and read live telemetry from the Worker
• Connect your own hardware: turn the scaffolded Worker into one for a real device
• Run a mining site end to end: boot the full demo site with several Worker families and a richer dashboard
• Wire a dashboard by hand: learn what the CLI scaffolds by assembling each piece yourself