Deploy the agent behind the Gateway

Mount the plugin

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-plugin-agent from its Gateway plugin catalog. mdk onboard's wizard supports creating a compliant mdk.yaml from scratch, interactively. Its entry carries a real repoPath (backend/plugins/agent), not a stub, so selecting it installs a working plugin rather than a placeholder.

1.1 B Add it to an existing mdk.yaml

Already have one from a previous onboarding run? Add the plugin under spec.gateway.plugins by hand, with the model provider, the MCP url, and the approval timeout under agent. Once published, that directory is node_modules/@tetherto/mdk-plugin-agent; in this monorepo checkout it is backend/plugins/agent. For example, a standalone gateway carrying just this plugin, reaching across to the full-site example's MCP tool server:

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

1.2 Run it

Once the mdk.yaml names the plugin, either way, run mdk run all.

A stack built for just this plugin declares no Workers, so all boots a Kernel it never actually uses (it only proxies chat to full-site's separate MCP server) alongside 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 full-site's own gateway (3007) never carries the agent plugin; this is a separate gateway, reaching across to full-site's MCP tool server on 3008.

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.