The integration model

Two extension points, named after what they extend

The naming is literal: a Worker plugin is a plugin for a Worker, a Gateway plugin is a plugin for the Gateway. Neither extends Kernel: Kernel has no plugin system, by design (see Architecture).

The contract: one file, three audiences

A Worker plugin's mdk-contract.json is read by three different consumers, none of which see a different copy:

• Kernel reads capabilities.telemetry[]/commands[] to validate that a command a caller sends is one the Worker actually declared, and to route by device family for write-permission checks (miner:w, container:w).
• The UI reads the same telemetry/command names and units to label a value without hard-coding a device's vocabulary.
• An AI agent reads the same contract at runtime to derive its tool set: a new device family means new agent tools with no change to the agent's own code (see the MCP server and runtime tool derivation).

One file, no drift between what the kernel enforces, what the UI shows, and what an agent can reason about.

mdk-plugin.json gets the same treatment, for Gateway plugins

A Gateway plugin's manifest declares its routes (id, handler, http.method/http.path, response schema, constraints, examples, errors, safety). The Gateway's plugin loader reads it to mount routes and validate the manifest shape at load time; nothing about it is hand-wired into the Gateway's own code path per plugin.

Workers are not only hardware

A Worker plugin wraps whatever answers to "one device, one connection, one set of telemetry/commands"; that's just as often a non-hardware integration:

• A pool API Worker: telemetry is your hashrate/earnings from the pool's own API, "commands" might be switching workers between pools; no physical device involved at all.
• An accounting sync Worker: telemetry is a ledger balance or a sync status pulled from a third-party service, with no ASIC anywhere in the picture.

Both get the exact same treatment from Kernel as a physical miner: identity, capabilities, telemetry pull, command dispatch. Kernel does not know or care that there is no hardware behind either one.

What this buys you

Write the integration once (one Worker plugin per device family, one Gateway plugin per route you need) and every consumer built against the standard round trip works with it for free: the same dashboard code, the same agent tooling, the same Gateway auth model, regardless of which device family or which route it's actually talking to underneath.

Contract versioning today

There is no enforced compatibility mechanism between contract versions today. A Worker plugin's mdk-contract.json has no version field of its own: the package's package.json semver is the only version signal, and nothing in Kernel or the Gateway checks it against a caller's expectations. In practice this means: a contract's shape is whatever the currently-loaded plugin declares, and there's no compatibility gate protecting a caller written against an older shape. If a contract's telemetry or command names change, that's a breaking change for anything built against the old names, with no automated warning today.

Next steps

• Build a Worker plugin for a new device family
• Understand the Gateway plugin authoring flow
• Understand the storage model: what a Worker plugin decides to persist
• Understand architecture: where both extension points sit in the round trip

Next steps

• Build a Worker plugin for a new device family
• Understand the storage model
• Understand architecture