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: 3847metadata 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 runmdk 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
| Key | Purpose | Taught by |
|---|---|---|
spec.kernel | Kernel port; written by mdk onboard, has no effect | None: no command uses it |
spec.gateway | Sets the Gateway port and Gateway settings | Gateway-wide settings |
spec.mcp | Configures the MCP server | MCP server settings for mdk run mcp |
spec.workers | Declares the Workers the stack runs | Declaring a Worker |
spec.apps | Registers and mounts apps | Declaring and mounting an app |
spec.rbac | Controls access: roles and who holds them | Writing the access policy |
spec.network | Configures a private DHT (spec.network.dht) | Running on a private DHT |
Next steps
- Run your Worker with the CLI: build a stack's
mdk.yamlone command at a time and run it - Look up a CLI command: every command that reads or writes
mdk.yaml, with its flags - Resolve variables in
mdk.yaml: keep secrets out of the file with${VAR}placeholders