MDK Logo

Stack file

The minimal `mdk.yaml` the CLI loads, and which page teaches each block under `spec`

Overview

mdk.yaml declares a stack: the Kernel, the Gateway, and the Workers, apps, and access policy that run with them. Every mdk command that reads a project loads it from the project directory. This page shows a minimal file the CLI accepts and maps each block under spec to the page that teaches it.

The file is what the mdk CLI both writes and reads. A stack started from code with @tetherto/mdk-core doesn't need it: the MVP site example runs a full site under PM2 from its own config, and Start apps from code shows the calls.

Minimal starting file

apiVersion: mdk/v1
kind: Stack
metadata:
  name: my-site
spec:
  gateway:
    port: 3847

metadata is optional: metadata.name names the stack, and the CLI assigns a name when it is missing.

Write the starter policy, then start the stack:

mdk rbac init
mdk run

mdk rbac init writes spec.rbac, and mdk run refuses to boot until it has. The other CLI commands write the rest: mdk onboard writes a complete file, mdk create and mdk add add Workers and apps, and mdk user add --admin binds a user to the admin role in spec.rbac. Edit the blocks the key map points to, and leave the fields the CLI writes for its own use as it wrote them.

Keys under spec

KeyPurposeTaught by
spec.kernelKernel port; written by mdk onboard, has no effectNone: no command uses it
spec.gatewaySets the Gateway port and Gateway settingsGateway-wide settings
spec.mcpConfigures the MCP serverMCP server settings for mdk run mcp
spec.workersDeclares the Workers the stack runsDeclaring a Worker
spec.appsRegisters and mounts appsDeclaring and mounting an app
spec.rbacControls access: roles and who holds themWriting the access policy
spec.networkConfigures a private DHT (spec.network.dht)Running on a private DHT

Next steps

On this page