mdk-deployment

Files (1)

• SKILL.md

SKILL.md (first lines)

# Deploy and run an MDK stack

In CLI-managed projects (this folder), the stack is declared in `mdk.yaml` and
started with `mdk run`. Boot order matters: **Kernel → Workers → apps → Gateway/UI**.

## Project shape

```
<project>/
├── mdk.yaml                 # Stack spec (source of truth)
├── package.json             # private root manifest; links workers/<name> and apps/<name> by file: deps
├── workers/<name>/          # Worker Plugin packages (mdk create worker)
├── apps/<name>/             # apps: mdk-app.yaml + plugin/ route table (mdk create app)
├── apps/dashboard/          # UI shell (mdk create dashboard)
└── .mdk/                    # runtime state written by `mdk run` — gitignored, disposable
```

Workers and apps are linked from the root manifest by relative `file:`
dependencies: one root `npm install` links every component into the project's
`node_modules`, which is how `mdk run` resolves them. The dashboard is
deliberately **not** linked — it links the MDK UI packages by `file:` path and
installs on its own, so its React is never hoisted alongside those links.

## `mdk.yaml` essentials

```yaml
apiVersion: mdk/v1
kind: Stack
metadata:
  name: <stack-name>
spec:
  kernel:
    port: 3848
  gateway:
    port: 3847
  apps:
    - name: <app-name>                 # ^[a-z][a-z0-9-]*$; routes served under /apps/<app-name>
      package: <app-package-name>      # e.g. fleet-summary, or @org/name
      config: {}                       # overrides the mdk-app.yaml config defaults
      # mount: /                       # serve at the Gateway root (required for @tetherto/mdk-app-agent)
  mcp:
    port: 3947   # optional — defaults to gateway.port + 100
  workers:
    - name: <worker-name>
      package: ./workers/<worker-name>   # local path, or an installed npm name
      config:
        mock: true
        devices:
          - id: dev-0
            opts: { host: 127.0.0.1, port: 18080, serial: DEV-0 }
```

Both `mdk create worker <name>` and `mdk create app <name>` scaffold the
package **and** register it here automatically (Workers under
`spec.workers`, apps under `spec.apps`) — no manual
`package.json` linking step. `create worker` also seeds a stack-unique mock port/device id
per Worker, so scaffolding several in one project never collides. A published
package goes through `mdk add app <npm-or-github-source>` / `mdk add worker <source>`,
which installs it, validates it, and only then adds the entry. If you add a
package by hand instead, mirror that: `npm install` at the project root, append the
entry yourself, then check it with `mdk validate app <name>` / `mdk validate worker <name>`.

`spec.gateway.plugins` is rejected by the CLI; move each entry to `spec.apps` with a `name`.

## Run commands

```bash
mdk run                     # whole stack from mdk.yaml: kernel + workers + one process per app + gateway
mdk run kernel
mdk run gateway
mdk run worker <name>       # e.g. mdk run worker demo-miner
mdk run app <name>          # one app runtime, in the foreground
mdk run dashboard           # the scaffolded UI shell's dev server
mdk run mcp                 # standalone MCP server for AI agents (needs Kernel running first)
```

`mdk run` with no target boots everything together; that's not a spec setting,
just which command you type. Use the per-component targets and separate
terminals when debugging one tier. Gateway port is `spec.gateway.port`
(example: `3847`); curl an app at `http://127.0.0.1:<gateway-port>/apps/<app-name>/api/...`
(or at `/api/...` when its entry sets `mount: /`). Each app runs in its own runtime process
and accepts calls only from the Gateway's key; the Gateway forwards each request to it.

Like the dashboard, `mcp` is never part of the default `all` target — always
start it explicitly, in its own terminal, after `mdk run kernel` (a standalone
`run mcp` has no in-process Kernel handle to reuse). It reads `spec.apps` and exposes each
declared app's routes as agent-callable tools, over `spec.mcp.port` if set,
else `spec.gateway.port + 100`. Routes not marked `"safety": "read-only"` are withheld
unless it is started with `--allow-write`.

Every caller publishes its Kernel key to `.mdk/trusted-keys/` (`gateway.pub`, `mcp.pub`,
`cli.pub`, `app-<name>.pub`, …) and the fail-closed Kernel admits it with full access: an app's
`permissions` in `mdk-app.yaml` are not enforced yet.

Ctrl+C / SIGTERM stops components in reverse boot order (Gateway → apps → Workers →
Kernel) and always exits, even if a component's own shutdown hangs.

### Verify

```bash
mdk status                              # environment + Kernel/Gateway/worker health, exit code encodes it
mdk status -o json | jq .health
curl -s http://127.0.0.1:3847/apps/<app-name>/api/<route> | jq .
```

`mdk status` never starts, stops or repairs anything — it probes the Kernel
over HRPC and the Gateway over HTTP, reports declared-vs-registered Workers, and
counts an app as running while a live process holds its run lock.
Exit codes: `0` healthy, `4` precondition not met (bad Node, invalid
`mdk.yaml`, packages not installed), `5` stack not fully up.

UI: `mdk run dashboard` (or `cd apps/dashboard && npm run dev` directly) and
open the page route added by `mdk-ui-component`.

## Scaffolding helpers

| Need               | Command                                                |
| ------------------ | ------------------------------------------------------ |
| Guided `mdk.yaml`  | `mdk onboard`                                          |

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk