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 @mdk/ork.
A concrete request and response pair, end to end:
// request: App Node asks @mdk/ork 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: @mdk/ork 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; @mdk/ork detects its peer connection automatically |
identity.request | request | @mdk/ork to Worker | Requests the worker's identity and managed devices |
capability.request | request | @mdk/ork to Worker | Asks the worker to declare its full capability schema |
state.pull | request | @mdk/ork to Worker | Worker returns a snapshot of state-machine status (low cadence tick, e.g., 60s) |
telemetry.pull | request | @mdk/ork to Worker | Worker returns device metrics plus history (medium cadence tick, e.g., 10s) |
command.request | request | @mdk/ork to Worker | Resolves the worker by deviceId and dispatches the command for execution |
health.ping | request | @mdk/ork 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