Deploy the agent behind the Gateway

Mount the app

Either:

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

1.1 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: /.

1.1 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
  rbac:
    enforcement: deny
    roles:
      - name: agent-operator
        rules:
          - resources: [agent/*]
            verbs: [get, list, create, update, delete]
    bindings:
      - role: agent-operator
        subjects: [{ kind: ServiceAccount, name: operator-agent }]

spec.rbac is what lets a caller reach the app's routes, and a stack without one denies every route. A route is governed as <app>/<path>, so agent/* covers everything this app serves whatever its paths are. To name routes individually instead, take them from the app's own route table and write them as resources and verbs inside a role and its bindings. mdk rbac apply hands an edited policy to a Kernel that is already running, and a binding's subject is a user or a service account you create.

1.2 Run it

Once the mdk.yaml names the app, either way:

mdk sa add operator-agent   # the credential the caller below signs in with; the Kernel registers it at the next start
mdk rbac init               # binds the CLI's own account and grants the app the Kernel access its manifest asks for
mdk run

mdk run refuses to boot a Kernel that nobody can administer, so without mdk rbac init it exits with spec.rbac binds nobody. mdk run then 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.

TOKEN=$(mdk sa token operator-agent)

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.