See an app serve your data

Create a project

mkdir fleet-demo && cd fleet-demo

Write a minimal mdk.yaml:

apiVersion: mdk/v1
kind: Stack
metadata:
  name: fleet-demo
spec:
  workers: []
  gateway:
    port: 3847
  apps: []

mdk onboard writes the same file interactively; this tutorial keeps it to the fields it uses.

Scaffold a Worker and an app

mdk create worker demo-miner
mdk create app fleet

Each command copies a template, links the package into the project's package.json, runs npm install, and adds an entry to mdk.yaml: the Worker under spec.workers with a mock: true seed device, the app under spec.apps. mdk create app also builds the app's starter UI into ui/ and writes the app's grant into spec.rbac: the role and binding that give it the Kernel access its manifest requests.

Run the stack

mdk rbac init
mdk run

mdk rbac init completes spec.rbac: it binds the CLI's own account to an admin role and reports the app grant that mdk create app already wrote as in place. Without the admin binding mdk run refuses to boot a Kernel nobody could administer.

mdk run boots the Kernel, the Worker and its mock device, one runtime process for the app, then the Gateway. Leave it running. No app route is open, so create the first operator from a second terminal, sign in, and call the route with the access token:

mdk user add ops@example.com --admin   # prompts for a password of at least 12 characters; the Kernel must still be running

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

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

Expected output:

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

A workerCount of 0 means the Worker has not registered yet; call again after a few seconds. That JSON came from a route the Gateway did not have until the stack declared an app that serves it.

Read the files that produced it

The parts of the app this tutorial exercises are a manifest, a route table and a controller. The scaffold also ships a starter UI, which no step here opens:

apps/fleet/
├── mdk-app.yaml               # id, version, displayName, permissions, config defaults
├── plugin/
│   ├── mdk-plugin.json        # the route table the Gateway reads
│   ├── lib/client.js          # the app's MDK client
│   └── controllers/summary.js # the handler
├── ui-src/                    # starter page source, not used in this tutorial
└── ui/                        # that page, built by `mdk create app`

plugin/mdk-plugin.json declares the route: an id, the handler path, an http block giving the method and path, and "safety": "read-only", which is what lets mdk run mcp offer the route to an agent as a tool.

plugin/controllers/summary.js is the handler, shown abridged. Every controller is async function (req) and returns a plain object, which is sent back as JSON. It never touches a response object:

const mdkClient = require('../lib/client')

module.exports = async function summary (req) {
  const resp = await mdkClient.listWorkers()
  const workers = (resp && resp.workers) || []
  // ... count devices across every Worker and return the counts
}

The generated file also catches ERR_MDK_CLIENT_UNAVAILABLE and answers kernelConnected: false, so the route stays callable while the Kernel is still booting.

mdkClient, built once for the app in plugin/lib/client.js from require('@tetherto/mdk-gateway/plugin'), is the same protocol client used everywhere else in MDK. Aggregation lives here, in the app. Workers are structurally single-device, so a Worker can only ever answer for one device; combining them into a fleet view is the app's job.