Deploy the agent behind the Gateway

Mount the app

Either:

• Select it during onboarding, or
• Already have an mdk.yaml? Add it by hand

A Select it during onboarding

Run mdk onboard and select mdk-app-agent from its app catalog. mdk onboard's wizard supports creating a compliant mdk.yaml from scratch, interactively. It installs @tetherto/mdk-app-agent by package name and writes its spec.apps entry with mount: /.

B Add it to an existing mdk.yaml

Already have one from a previous onboarding run? Add the app under spec.apps by hand, with mount: / and the model provider, the MCP url, and the approval timeout under agent. The app resolves from node_modules/@tetherto/mdk-app-agent. For example, a standalone gateway carrying just this app, reaching across to the MVP site example's MCP tool server:

apiVersion: mdk/v1
kind: Stack
metadata:
  name: agent-gateway
spec:
  workers: []
  gateway:
    port: 3847
  apps:
    - name: agent
      package: "@tetherto/mdk-app-agent"
      mount: /
      config:
        agent:
          provider: { kind: qvac, model: qwen3-4b, baseURL: http://127.0.0.1:11500/v1 }
          mcp: { url: http://127.0.0.1:3101/mcp }
          approvalTimeoutMs: 120000

1.2 Run it

Once the mdk.yaml names the app, either way, write the access policy before the first run:

mdk rbac init

mdk run refuses a stack whose spec.rbac binds nobody, because the Kernel would boot with nobody able to administer it. mdk rbac init writes the starter policy: an admin role, the CLI bound to it, and the Gateway and MCP server bound to read policy. Step 4 of the security blueprint covers what it writes and how to change it.

Then run mdk run. It starts the app in its own runtime process and the Gateway forwards the agent routes to it.

A stack built for just this app declares no Workers, so mdk run boots a Kernel it never actually uses (it only proxies chat to the MVP site's separate MCP server) alongside the app and the Gateway.

Create a session and send a message

Use the port your mdk.yaml gave the gateway: 3847 in the example above. Note that the MVP site's own gateway (3000) never carries the agent app; this is a separate gateway, reaching across to the MVP site's MCP tool server on 3101.

Sign in first. The access token comes back in the response body; every call below carries it.

TOKEN=$(curl -s -X POST http://localhost:<port>/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"<name>","password":"<password>"}' | jq -r .accessToken)

curl -X POST http://localhost:<port>/agent/sessions \
  -H "Authorization: Bearer $TOKEN"
# {"sessionId":"..."}

curl -N -X POST http://localhost:<port>/agent/sessions/<id>/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text":"how many miners are on the site?"}'

The response streams as text/event-stream. A read-only question ends in tool_call, tool_result, token, and done events, each stamped with the turn's turnId and a monotonic seq.

Approve a write

A write action pauses the turn instead of running it:

event: pending_approval
data: {"type":"pending_approval","name":"act_device","args":{"ref":"whatsminer-0","action":"reboot"},"approvalId":"..."}

Decide it from the paused stream's approvalId:

curl -X POST http://localhost:<port>/agent/sessions/<id>/approvals/<approvalId> \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"approved":true}'

Approving resumes the same stream: the tool runs for real, and the turn continues to its token and done events. Rejecting, or letting the approval window expire, resolves to false, and the write never runs.