Handbook

Matrix channel + agent bus (OpenClaw extension)

Operator guide: Agent communication on the Platform handbook.

Updated 2026-07-26

Forge Matrix/Element is the human gateway for agent control from phone or browser. Machine traffic uses NATS JetStream on Granite; workers do not speak Matrix as their primary protocol.

Lane

Element (element.forgedc.net)
  → Matrix adapter (forge-cursor-bridge matrix-adapter)
       ↕ forge.chat_intent.v1 / forge.agent_event.v1
  → NATS JetStream (Granite, private)
       ↕ agents.cursor.cmd / agents.cursor.evt
  → Cursor worker (laptop, cursor-agent CLI + model selection)

Chat can request. Lenses govern (future). Fleet/workers execute.

Repos

Repo	Role
forge-matrix	Synapse, Element, Postgres, NATS on Granite
forge-cursor-bridge	Matrix adapter + Cursor worker + envelopes

Hostnames

matrix.forgedc.net — Synapse (server_name, sticky)
element.forgedc.net — Element Web UI
NATS — 127.0.0.1:4222 on Granite only; laptop via forge-matrix/scripts/nats-ssh-tunnel.sh

ChatIntent mapping

Field	Matrix adapter value
`source.gateway`	`matrix`
`source.channel`	room id or alias (`#cursor:matrix.forgedc.net`)
`source.sender_ref`	Matrix user id
`requested_action`	parsed `!agent` command

Adapter logs forge.chat_intent.v1 JSON at ingress (see bridge envelopes/chat_intent.py).

v1 scope

Headless cursor-agent CLI agents (--print, --model, --resume); not IDE Composer tab control
#cursor / #ops rooms unencrypted for bot reliability
Closed Matrix federation; invite-only accounts

Operate

See forge-matrix/README.md and forge-cursor-bridge/README.md.

Forge Platform