Protocol messages
Envelope schema, request/response examples, action catalogue, and base command set.
Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page is the canonical spec for that envelope, the full set of protocol actions, and the base command set every Worker must support. For the architectural narrative explaining when each action fires, see Architecture.
Envelope
{
"id": "uuid-v4",
"version": "0.1.0",
"type": "request | response | event",
"action": "<protocol action>",
"sender": "<component:type:instance>",
"target": "<component:type:instance> | null",
"deviceId": "string | null",
"timestamp": 1711640000000,
"payload": {}
}External consumers (UI or AI agents) only provide deviceId; the target Worker identity is internally resolved by @tetherto/mdk-kernel.
A concrete request and response pair, end to end:
// request: Gateway asks @tetherto/mdk-kernel to reboot device wm001
{
"id": "8d1c-e3a4",
"version": "0.1.0",
"type": "request",
"action": "command.request",
"sender": "appNode:fleet-api:1",
"target": null,
"deviceId": "wm001",
"timestamp": 1711640000000,
"payload": { "command": "reboot" }
}
// response: @tetherto/mdk-kernel relays the worker's terminal result
{
"id": "1f9b-77c2",
"version": "0.1.0",
"type": "response",
"action": "command.result",
"sender": "ork:kernel:tx-1",
"target": "appNode:fleet-api:1",
"deviceId": "wm001",
"timestamp": 1711640002145,
"payload": { "status": "SUCCESS", "elapsedMs": 2145 }
}Actions
| Action | Type | Direction | Purpose |
|---|---|---|---|
| (DHT presence) | passive | Worker to DHT topic | Worker joins a known Hyperswarm topic; @tetherto/mdk-kernel detects its peer connection automatically |
identity.request | request | @tetherto/mdk-kernel to Worker | Requests the Worker's identity and managed devices |
capability.request | request | @tetherto/mdk-kernel to Worker | Asks the Worker to declare its full capability schema |
state.pull | request | @tetherto/mdk-kernel to Worker | Worker returns a snapshot of state-machine status (low cadence tick, e.g., 60s) |
telemetry.pull | request | @tetherto/mdk-kernel to Worker | Worker returns device metrics plus history (medium cadence tick, e.g., 10s) |
command.request | request | @tetherto/mdk-kernel to Worker | Resolves the Worker by deviceId and dispatches the command for execution |
health.ping | request | @tetherto/mdk-kernel to Worker | Liveness probe (high cadence tick, e.g., 5s) |
Base command set
The protocol standardizes a Base Command Set supported by every Worker:
getConfig: retrieve current device configurationsetConfig: update device configuration parametershealth: fetch detailed diagnostic health status from the device