Control plane
How App Node, ORK, and Workers communicate in MDK
Overview
The MDK control plane concept covers authenticated requests, live reads, command dispatch, and approval-gated writes. It spans the App Node, ORK, and Workers, but each layer owns a different responsibility.
Use this page to understand which layer receives a request, which layer validates it, and when a write becomes a command.
For package-level APIs and configuration, use the App Node README, ORK README, and Worker README.
Responsibility boundaries
App Node owns the consumer-facing surface, including HTTP, WebSocket, MCP, plugins, authentication, and RBAC. Browser UIs and agents should enter MDK through the App Node (they do not talk to ORK directly).
ORK owns kernel coordination: Worker registry, telemetry routing, health checks, command dispatch, command state, and the write-action approval modules. ORK trusts established callers; it does not validate user identity.
Workers own hardware integration. They declare capabilities, answer ORK-initiated telemetry and state pulls, resolve candidate write calls for approval-gated actions, and execute final commands against devices.
Connection direction
The direction of each connection is intentional:
- Consumers call the App Node over HTTP, WebSocket, or MCP
- The App Node dials ORK over IPC or HRPC through
@tetherto/mdk-client - ORK discovers Workers, then initiates every Worker RPC
- Workers never initiate upstream calls to ORK or the App Node
The deployment topologies and Workers discovery model pages cover how this changes across single-process, local, and distributed deployments.
Request paths
Read requests
Reads usually start in an App Node route or plugin controller, pass through services.mdkClient, and reach ORK as registry,
capability, telemetry, or state queries. ORK routes Worker-owned reads down to the relevant Worker and returns the result to the
App Node. App Node controllers can combine live ORK data with persisted local data from services.dataProxy.
For plugin controller mechanics, use the App Node plugins guide.
Direct commands
Direct commands are immediate writes that do not require approval. The App Node validates the request and RBAC at the route layer,
then sends a command.request to ORK. ORK resolves the owning Worker, validates the command against the Worker's capabilities,
and hands the command to the crash-recoverable command state machine.
For command-dispatch module details, use the ORK README.
Approval-gated writes
Some writes are staged for approval before they become commands. This keeps direct commands available while adding a separate review path for fleet-changing actions that need operator approval.
The App Node owns the /auth/actions* HTTP surface and checks route-level RBAC such as actions:w. ORK owns
ActionManager, ActionCaller, and target permission checks at the protocol layer. Those ORK checks use the target
Worker's device family, such as miner:w or container:w, before resolving or approving writes. Workers answer
write.calls.request while ORK resolves candidate writes, then execute the final command.request after the configured vote
thresholds are met.
For implementation steps, use the write-actions how-to. For React hook names and exports, use the React adapter README.
Developer surfaces
The write-action flow is reachable from two different layers depending on where you are building.
| Layer | Package | How you call it |
|---|---|---|
| React / UI | @tetherto/mdk-react-adapter | Six hooks: useSubmitSingleAction, useSubmitPendingActions, useVoteOnAction, useCancelAction, usePendingActions, useLiveActions — call the App Node /auth/actions* routes |
| Backend / Node.js | @tetherto/mdk-client | Methods: pushAction, pushActionsBatch, voteAction, cancelActionsBatch, getAction, getActionsBatch, queryActions — send MDK Protocol envelopes directly to ORK |
The React hooks go through the App Node, which enforces JWT validation and RBAC (actions:w) for every request. The mdk-client
methods connect directly to ORK as trusted backend processes — ORK trusts any caller that can reach its socket or HRPC endpoint,
so the network or infrastructure layer is the admission gate, not the protocol.
Next steps
- Build App Node routes with the plugin guide
- Submit and approve write actions with the write-actions how-to
- Review ORK modules in the ORK README
- Review Worker capabilities in the Worker base README
Next steps
Learn more about: