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.

Related: OpenClaw integration, Matrix channel notes.

Hostnames

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

Repos

---

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. Cursor bridge on your laptop

cd forge-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

---

3. 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

---

4. Script reference

---

5. 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.