VuongKB/infrastructure/vm-102-matrix-appservice.md

created, id, keywords, links, modified, summary, tags, title

created	id	keywords	links	modified	summary	tags	title
2026-04-11T16:32:18+00:00	95ffbaa1-728e-434c-85d9-e82346f77d1e	matrix.pfi.local appservice as_token hs_token aipa-bridge matrix_bridge.py 8009 send_notification virtual-users room-routing element		2026-04-11T16:32:18+00:00	AIPA Matrix Application Service bridge setup for VM 102. Covers appservice registration, agent virtual users, room routing, env vars, operational notes, and troubleshooting.	infrastructure pfi pfi-ana matrix docker vm-102 appservice bridge aipa deployment integration	VM 102 — Matrix Appservice Configuration

The AIPA Matrix bridge registers with Synapse as an Application Service. Synapse pushes events to the bridge (no polling). The bridge manages virtual users for each agent.

Agent Virtual Users

Agent	Matrix ID	Display Name
Atlas	@atlas:matrix.pfi.local	Atlas
Linus	@linus:matrix.pfi.local	Linus
Hermione	@hermione:matrix.pfi.local	Hermione

These are virtual — managed entirely by the bridge. Do not register them as real Synapse accounts.

Setup Steps

1. Generate tokens

python3 -c "import secrets; print(secrets.token_hex(32))"  # as_token (bridge → Synapse)
python3 -c "import secrets; print(secrets.token_hex(32))"  # hs_token (Synapse → bridge)

2. Create appservice registration

File: /opt/docker/data/synapse/aipa_appservice.yaml

id: aipa-bridge
url: http://<BRIDGE_HOST_IP>:8009
as_token: "<AS_TOKEN>"
hs_token: "<HS_TOKEN>"
sender_localpart: aipa-bot
namespaces:
  users:
    - exclusive: true
      regex: "@(atlas|linus|hermione):.*"
  rooms: []
  aliases: []
rate_limited: false

exclusive: true means only the bridge can act as those users. url must be reachable from inside the Synapse container.

Restart Synapse: cd /opt/docker/compose/synapse && docker compose restart synapse

3. Configure AIPA environment

Add to env.sh:

export MATRIX_HOMESERVER_URL="http://localhost:8008"
export MATRIX_SERVER_NAME="matrix.pfi.local"
export MATRIX_AS_TOKEN="<as_token>"
export MATRIX_HS_TOKEN="<hs_token>"
# export MATRIX_DEFAULT_ROOM="!roomid:matrix.pfi.local"

Uncomment matrix: block in config/providers.yaml:

matrix:
  homeserver_url: "${MATRIX_HOMESERVER_URL}"
  server_name: "${MATRIX_SERVER_NAME}"
  as_token: "${MATRIX_AS_TOKEN}"
  hs_token: "${MATRIX_HS_TOKEN}"
  bridge_host: "0.0.0.0"
  bridge_port: 8009
  default_notification_room: "${MATRIX_DEFAULT_ROOM}"
  agents:
    atlas:
      display_name: "Atlas"
    linus:
      display_name: "Linus"
    hermione:
      display_name: "Hermione"

4. Start bridge

source .venv/bin/activate && source env.sh
python -m core.matrix_bridge

5. First use

1. Open Element at http://10.250.50.70:8080
2. Log in with admin account (server: matrix.pfi.local)
3. DM @atlas:matrix.pfi.local
4. Send a message — bridge routes to Atlas

Room Routing

1. User invites agent to room → bridge receives m.room.member invite
2. Agent auto-joins
3. Room permanently mapped to that agent in sessions/matrix_rooms.json
4. All subsequent messages routed to mapped agent
5. Multiple agents in same room: first invite wins for session, others get their own session

Operational Notes

• Session persistence: rooms mapped in sessions/matrix_rooms.json survive restarts. Reset with /reset or delete entry.
• Formatting: markdown→HTML conversion (format: org.matrix.custom.html)
• Typing indicators: bridge sends m.typing while agent processes
• Proactive notifications: agents call send_notification(content, channel="!roomid:matrix.pfi.local")
• Virtual users always show offline — expected, no presence for appservice users

Troubleshooting

Symptom	Cause	Fix
Synapse doesn't push events	Appservice URL wrong	Verify url reachable from Synapse container
Agent joins but doesn't respond	hs_token mismatch	Verify token matches MATRIX_HS_TOKEN
401 errors from Synapse	as_token mismatch	Verify token matches MATRIX_AS_TOKEN
Messages loop	Bridge not filtering own messages	Check SENDER_LOCALPART filter
Agent always offline	Expected	Normal for virtual users

Dependencies

• markdown (pip install markdown)
• fastapi, httpx

Security

• as_token and hs_token are admin-equivalent secrets
• Bridge authenticates Synapse pushes via MATRIX_HS_TOKEN (rejects 403 without it)
• Restrict port 8009 to internal access only