Agent communication

Architecture

Lane (v1):

1. You send !agent … in Element (#cursor room).
2. Matrix adapter emits envelopes (and logs forge.chat_intent.v1).
3. Cursor worker runs a local headless agent (not IDE Composer tabs).
4. Status returns to the room via the adapter.

Future agents subscribe to the same NATS subjects; they do not use Matrix as their primary protocol.

Communication agent (!comm): deterministic KB answers for Forge Intelligence, Platform, and Blueprints handbooks. Deployed via forge-agents on Granite; see Communication agent.

Related: OpenClaw integration, Matrix channel notes.

Hostnames

Registration is disabled. Accounts are created by an operator on Granite.

Repos

Governance and agent catalog: Forge Agents handbook. Orchestrator registry and Granite deploy: orchestrator, forge-agents repo.

---

1. Matrix + Element on Granite

From your workstation (Code/forge-matrix):

cd forge-matrix
cp .env.example .env
./scripts/generate-secrets.sh
./scripts/bootstrap-synapse.sh
./scripts/install-on-granite.sh

Cloudflare tunnel + DNS (uses CLOUDFLARE_API_TOKEN from forge-knowledge-assistant/.env.local when present):

./scripts/apply-cf-matrix-tunnel.sh
python3 scripts/ensure-matrix-dns.py

Tunnel target is the Precision SSH connector on Granite (CF_TUNNEL_ID in .env).

Create operator accounts

On Granite:

cd ~/forge-matrix
docker compose exec -T synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008 \
  -u forgeadmin -p 'YOUR_PASSWORD' -a --exists-ok

docker compose exec -T synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008 \
  -u cursorbot -p 'BOT_PASSWORD' --no-admin --exists-ok

Create rooms (from laptop, with admin password):

export MATRIX_HOMESERVER=https://matrix.forgedc.net
export MATRIX_ADMIN_USER=forgeadmin
export MATRIX_ADMIN_PASSWORD='YOUR_PASSWORD'
python3 scripts/setup-matrix-rooms.py

Rooms: #cursor, #ops, space #forge-agents. Keep #cursor and #ops unencrypted so the bot can read messages.

Sign in (web or mobile)

• Element Web: https://element.forgedc.net
• Homeserver: https://matrix.forgedc.net
• Username: local part only (e.g. forgeadmin)

Mobile: choose Sign in / I already have an account — not Create account.
If you see Registration has been disabled, the app is on the sign-up path; go back and use Sign in.

Alternatives on phone: open Element Web in the browser, or pair with desktop via Sign in with QR code.

---

2. WhatsApp relay (Element ↔ WhatsApp ↔ Android Auto)

Optional self-hosted bridge for operating an Element room from WhatsApp (and Android Auto on the relay phone). This is separate from the Cursor/NATS agent bridge.

Deploy and verify on Granite — see forge-matrix/README.md → WhatsApp relay bridge:

cd forge-matrix
./scripts/install-on-granite.sh
ssh granite 'cd ~/forge-matrix && ./scripts/verify-whatsapp-bridge.sh'

Operator steps (QR login, !wa bridge, 14-day phone keepalive): ./scripts/whatsapp-relay-setup-guide.sh

Do not bridge #cursor or other agent rooms.

WA queue notify (forge-wa-notify)

Optional service: invite @wanotify to Matrix rooms; each message is summarized via Granite LLM and queued to operator WhatsApp +380935502637 through the existing @warelay portal room (not a second WhatsApp login).

Deploy on Granite — see forge-matrix/README.md → WA queue notify bot and forge-wa-notify/README.md.

Operator WhatsApp commands: wait, details, reply, next, skip, clean (30-minute timeout advances the queue).

---

3. Cursor bridge on your laptop

Prefer the forge-agents package (migrated from forge-cursor-bridge):

cd forge-agents/packages/cursor_bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Edit .env:

CURSOR_API_KEY is required for !agent new even though agents run locally — the SDK authenticates headless runs on your machine.

Run

forge-cursor-bridge matrix-adapter

Or install the user service:

./scripts/install-user-service.sh
systemctl --user enable --now forge-cursor-bridge.service

Commands in #cursor

!agent new /home/you/Code/forgesdlc | Summarize the generator layout
!agent list
!agent send <agent_id> Add a test for the parser
!agent cancel <agent_id>
!agent status <agent_id>
!agent help

---

4. NATS agent bus (multi-agent)

NATS runs inside the Granite compose stack. It is not on the public internet.

SSH tunnel from laptop:

# forge-matrix/scripts/nats-ssh-tunnel.sh
ssh -N -L 4222:127.0.0.1:4222 granite

In forge-cursor-bridge/.env:

TRANSPORT=nats
NATS_URL=nats://USER:PASS@127.0.0.1:4222

Run adapter and worker (or use matrix-adapter which embeds the worker). Test the bus:

forge-cursor-bridge echo-agent

---

5. Script reference

---

6. Troubleshooting

---

Security boundaries

• Matrix federation is closed; registration is off.
• NATS is localhost on Granite or reached via SSH tunnel — not exposed publicly.
• Bridge allowlists Matrix user IDs and working-directory paths.
• Headless Cursor agents do not open IDE chat tabs; they use the same account auth as the SDK/CLI.