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. Its entry carries a real repoPath (backend/apps/agent), not a stub, so selecting it installs a working app rather than a placeholder, and the wizard 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. Once published, that directory is node_modules/@tetherto/mdk-app-agent; in this monorepo checkout it is backend/apps/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, 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.

curl -X POST http://localhost:<port>/agent/sessions
# {"sessionId":"..."}

curl -N -X POST http://localhost:<port>/agent/sessions/<id>/messages \
  -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 '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.