​
Matrix (plugin)

Matrix is the Matrix channel plugin for Pllan. It uses the official matrix-js-sdk and supports DMs, rooms, threads, media, reactions, polls, location, and E2EE.

​
Plugin required

Matrix is a plugin and is not bundled with core Pllan. Install from npm: 
pllan plugins install @pllan/matrix
Install from a local checkout: 
pllan plugins install ./extensions/matrix
See Plugins for plugin behavior and install rules.

​
Setup

  1. Install the plugin.
  2. Create a Matrix account on your homeserver.
  3. Configure channels.matrix with either:
    • homeserver + accessToken, or
    • homeserver + userId + password.
  4. Restart the gateway.
  5. Start a DM with the bot or invite it to a room.
Interactive setup paths: 
pllan channels add
pllan configure --section channels
What the Matrix wizard actually asks for:
  • homeserver URL
  • auth method: access token or password
  • user ID only when you choose password auth
  • optional device name
  • whether to enable E2EE
  • whether to configure Matrix room access now
Wizard behavior that matters:
  • If Matrix auth env vars already exist for the selected account, and that account does not already have auth saved in config, the wizard offers an env shortcut and only writes enabled: true for that account.
  • When you add another Matrix account interactively, the entered account name is normalized into the account ID used in config and env vars. For example, Ops Bot becomes ops-bot.
  • DM allowlist prompts accept full @user:server values immediately. Display names only work when live directory lookup finds one exact match; otherwise the wizard asks you to retry with a full Matrix ID.
  • Room allowlist prompts accept room IDs and aliases directly. They can also resolve joined-room names live, but unresolved names are only kept as typed during setup and are ignored later by runtime allowlist resolution. Prefer !room:server or #alias:server.
  • Runtime room/session identity uses the stable Matrix room ID. Room-declared aliases are only used as lookup inputs, not as the long-term session key or stable group identity.
  • To resolve room names before saving them, use pllan channels resolve --channel matrix "Project Room".
Minimal token-based setup: 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}
Password-based setup (token is cached after login): 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "Pllan Gateway",
    },
  },
}
Matrix stores cached credentials in ~/.pllan/credentials/matrix/. The default account uses credentials.json; named accounts use credentials-<account>.json. Environment variable equivalents (used when the config key is not set):
  • MATRIX_HOMESERVER
  • MATRIX_ACCESS_TOKEN
  • MATRIX_USER_ID
  • MATRIX_PASSWORD
  • MATRIX_DEVICE_ID
  • MATRIX_DEVICE_NAME
For non-default accounts, use account-scoped env vars:
  • MATRIX_<ACCOUNT_ID>_HOMESERVER
  • MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
  • MATRIX_<ACCOUNT_ID>_USER_ID
  • MATRIX_<ACCOUNT_ID>_PASSWORD
  • MATRIX_<ACCOUNT_ID>_DEVICE_ID
  • MATRIX_<ACCOUNT_ID>_DEVICE_NAME
Example for account ops:
  • MATRIX_OPS_HOMESERVER
  • MATRIX_OPS_ACCESS_TOKEN
For normalized account ID ops-bot, use:
  • MATRIX_OPS_BOT_HOMESERVER
  • MATRIX_OPS_BOT_ACCESS_TOKEN
The interactive wizard only offers the env-var shortcut when those auth env vars are already present and the selected account does not already have Matrix auth saved in config.

​
Configuration example

This is a practical baseline config with DM pairing, room allowlist, and E2EE enabled: 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
    },
  },
}

​
E2EE setup

​
Bot to bot rooms

By default, Matrix messages from other configured Pllan Matrix accounts are ignored. Use allowBots when you intentionally want inter-agent Matrix traffic: 
{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
  • allowBots: true accepts messages from other configured Matrix bot accounts in allowed rooms and DMs.
  • allowBots: "mentions" accepts those messages only when they visibly mention this bot in rooms. DMs are still allowed.
  • groups.<room>.allowBots overrides the account-level setting for one room.
  • Pllan still ignores messages from the same Matrix user ID to avoid self-reply loops.
  • Matrix does not expose a native bot flag here; Pllan treats “bot-authored” as “sent by another configured Matrix account on this Pllan gateway”.
Use strict room allowlists and mention requirements when enabling bot-to-bot traffic in shared rooms. Enable encryption: 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}
Check verification status: 
pllan matrix verify status
Verbose status (full diagnostics): 
pllan matrix verify status --verbose
Include the stored recovery key in machine-readable output: 
pllan matrix verify status --include-recovery-key --json
Bootstrap cross-signing and verification state: 
pllan matrix verify bootstrap
Multi-account support: use channels.matrix.accounts with per-account credentials and optional name. See Configuration reference for the shared pattern. Verbose bootstrap diagnostics: 
pllan matrix verify bootstrap --verbose
Force a fresh cross-signing identity reset before bootstrapping: 
pllan matrix verify bootstrap --force-reset-cross-signing
Verify this device with a recovery key: 
pllan matrix verify device "<your-recovery-key>"
Verbose device verification details: 
pllan matrix verify device "<your-recovery-key>" --verbose
Check room-key backup health: 
pllan matrix verify backup status
Verbose backup health diagnostics: 
pllan matrix verify backup status --verbose
Restore room keys from server backup: 
pllan matrix verify backup restore
Verbose restore diagnostics: 
pllan matrix verify backup restore --verbose
Delete the current server backup and create a fresh backup baseline: 
pllan matrix verify backup reset --yes
All verify commands are concise by default (including quiet internal SDK logging) and show detailed diagnostics only with --verbose. Use --json for full machine-readable output when scripting. In multi-account setups, Matrix CLI commands use the implicit Matrix default account unless you pass --account <id>. If you configure multiple named accounts, set channels.matrix.defaultAccount first or those implicit CLI operations will stop and ask you to choose an account explicitly. Use --account whenever you want verification or device operations to target a named account explicitly: 
pllan matrix verify status --account assistant
pllan matrix verify backup restore --account assistant
pllan matrix devices list --account assistant
When encryption is disabled or unavailable for a named account, Matrix warnings and verification errors point at that account’s config key, for example channels.matrix.accounts.assistant.encryption.

​
What “verified” means

Pllan treats this Matrix device as verified only when it is verified by your own cross-signing identity. In practice, pllan matrix verify status --verbose exposes three trust signals:
  • Locally trusted: this device is trusted by the current client only
  • Cross-signing verified: the SDK reports the device as verified through cross-signing
  • Signed by owner: the device is signed by your own self-signing key
Verified by owner becomes yes only when cross-signing verification or owner-signing is present. Local trust by itself is not enough for Pllan to treat the device as fully verified.

​
What bootstrap does

pllan matrix verify bootstrap is the repair and setup command for encrypted Matrix accounts. It does all of the following in order:
  • bootstraps secret storage, reusing an existing recovery key when possible
  • bootstraps cross-signing and uploads missing public cross-signing keys
  • attempts to mark and cross-sign the current device
  • creates a new server-side room-key backup if one does not already exist
If the homeserver requires interactive auth to upload cross-signing keys, Pllan tries the upload without auth first, then with m.login.dummy, then with m.login.password when channels.matrix.password is configured. Use --force-reset-cross-signing only when you intentionally want to discard the current cross-signing identity and create a new one. If you intentionally want to discard the current room-key backup and start a new backup baseline for future messages, use pllan matrix verify backup reset --yes. Do this only when you accept that unrecoverable old encrypted history will stay unavailable.

​
Fresh backup baseline

If you want to keep future encrypted messages working and accept losing unrecoverable old history, run these commands in order: 
pllan matrix verify backup reset --yes
pllan matrix verify backup status --verbose
pllan matrix verify status
Add --account <id> to each command when you want to target a named Matrix account explicitly.

​
Startup behavior

When encryption: true, Matrix defaults startupVerification to "if-unverified". On startup, if this device is still unverified, Matrix will request self-verification in another Matrix client, skip duplicate requests while one is already pending, and apply a local cooldown before retrying after restarts. Failed request attempts retry sooner than successful request creation by default. Set startupVerification: "off" to disable automatic startup requests, or tune startupVerificationCooldownHours if you want a shorter or longer retry window. Startup also performs a conservative crypto bootstrap pass automatically. That pass tries to reuse the current secret storage and cross-signing identity first, and avoids resetting cross-signing unless you run an explicit bootstrap repair flow. If startup finds broken bootstrap state and channels.matrix.password is configured, Pllan can attempt a stricter repair path. If the current device is already owner-signed, Pllan preserves that identity instead of resetting it automatically. Upgrading from the previous public Matrix plugin:
  • Pllan automatically reuses the same Matrix account, access token, and device identity when possible.
  • Before any actionable Matrix migration changes run, Pllan creates or reuses a recovery snapshot under ~/Backups/pllan-migrations/.
  • If you use multiple Matrix accounts, set channels.matrix.defaultAccount before upgrading from the old flat-store layout so Pllan knows which account should receive that shared legacy state.
  • If the previous plugin stored a Matrix room-key backup decryption key locally, startup or pllan doctor --fix will import it into the new recovery-key flow automatically.
  • If the Matrix access token changed after migration was prepared, startup now scans sibling token-hash storage roots for pending legacy restore state before giving up on the automatic backup restore.
  • If the Matrix access token changes later for the same account, homeserver, and user, Pllan now prefers reusing the most complete existing token-hash storage root instead of starting from an empty Matrix state directory.
  • On the next gateway start, backed-up room keys are restored automatically into the new crypto store.
  • If the old plugin had local-only room keys that were never backed up, Pllan will warn clearly. Those keys cannot be exported automatically from the previous rust crypto store, so some old encrypted history may remain unavailable until recovered manually.
  • See Matrix migration for the full upgrade flow, limits, recovery commands, and common migration messages.
Encrypted runtime state is organized under per-account, per-user token-hash roots in ~/.pllan/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/. That directory contains the sync store (bot-storage.json), crypto store (crypto/), recovery key file (recovery-key.json), IndexedDB snapshot (crypto-idb-snapshot.json), thread bindings (thread-bindings.json), and startup verification state (startup-verification.json) when those features are in use. When the token changes but the account identity stays the same, Pllan reuses the best existing root for that account/homeserver/user tuple so prior sync state, crypto state, thread bindings, and startup verification state remain visible.

​
Node crypto store model

Matrix E2EE in this plugin uses the official matrix-js-sdk Rust crypto path in Node. That path expects IndexedDB-backed persistence when you want crypto state to survive restarts. Pllan currently provides that in Node by:
  • using fake-indexeddb as the IndexedDB API shim expected by the SDK
  • restoring the Rust crypto IndexedDB contents from crypto-idb-snapshot.json before initRustCrypto
  • persisting the updated IndexedDB contents back to crypto-idb-snapshot.json after init and during runtime
This is compatibility/storage plumbing, not a custom crypto implementation. The snapshot file is sensitive runtime state and is stored with restrictive file permissions. Under Pllan’s security model, the gateway host and local Pllan state directory are already inside the trusted operator boundary, so this is primarily an operational durability concern rather than a separate remote trust boundary. Planned improvement:
  • add SecretRef support for persistent Matrix key material so recovery keys and related store-encryption secrets can be sourced from Pllan secrets providers instead of only local files

​
Automatic verification notices

Matrix now posts verification lifecycle notices directly into the strict DM verification room as m.notice messages. That includes:
  • verification request notices
  • verification ready notices (with explicit “Verify by emoji” guidance)
  • verification start and completion notices
  • SAS details (emoji and decimal) when available
Incoming verification requests from another Matrix client are tracked and auto-accepted by Pllan. For self-verification flows, Pllan also starts the SAS flow automatically when emoji verification becomes available and confirms its own side. For verification requests from another Matrix user/device, Pllan auto-accepts the request and then waits for the SAS flow to proceed normally. You still need to compare the emoji or decimal SAS in your Matrix client and confirm “They match” there to complete the verification. Pllan does not auto-accept self-initiated duplicate flows blindly. Startup skips creating a new request when a self-verification request is already pending. Verification protocol/system notices are not forwarded to the agent chat pipeline, so they do not produce NO_REPLY.

​
Device hygiene

Old Pllan-managed Matrix devices can accumulate on the account and make encrypted-room trust harder to reason about. List them with: 
pllan matrix devices list
Remove stale Pllan-managed devices with: 
pllan matrix devices prune-stale

​
Direct Room Repair

If direct-message state gets out of sync, Pllan can end up with stale m.direct mappings that point at old solo rooms instead of the live DM. Inspect the current mapping for a peer with: 
pllan matrix direct inspect --user-id @alice:example.org
Repair it with: 
pllan matrix direct repair --user-id @alice:example.org
Repair keeps the Matrix-specific logic inside the plugin:
  • it prefers a strict 1:1 DM that is already mapped in m.direct
  • otherwise it falls back to any currently joined strict 1:1 DM with that user
  • if no healthy DM exists, it creates a fresh direct room and rewrites m.direct to point at it
The repair flow does not delete old rooms automatically. It only picks the healthy DM and updates the mapping so new Matrix sends, verification notices, and other direct-message flows target the right room again.

​
Threads

Matrix supports native Matrix threads for both automatic replies and message-tool sends.
  • threadReplies: "off" keeps replies top-level.
  • threadReplies: "inbound" replies inside a thread only when the inbound message was already in that thread.
  • threadReplies: "always" keeps room replies in a thread rooted at the triggering message.
  • Inbound threaded messages include the thread root message as extra agent context.
  • Message-tool sends now auto-inherit the current Matrix thread when the target is the same room, or the same DM user target, unless an explicit threadId is provided.
  • Runtime thread bindings are supported for Matrix. /focus, /unfocus, /agents, /session idle, /session max-age, and thread-bound /acp spawn now work in Matrix rooms and DMs.
  • Top-level Matrix room/DM /focus creates a new Matrix thread and binds it to the target session when threadBindings.spawnSubagentSessions=true.
  • Running /focus or /acp spawn --thread here inside an existing Matrix thread binds that current thread instead.

​
Thread Binding Config

Matrix inherits global defaults from session.threadBindings, and also supports per-channel overrides:
  • threadBindings.enabled
  • threadBindings.idleHours
  • threadBindings.maxAgeHours
  • threadBindings.spawnSubagentSessions
  • threadBindings.spawnAcpSessions
Matrix thread-bound spawn flags are opt-in:
  • Set threadBindings.spawnSubagentSessions: true to allow top-level /focus to create and bind new Matrix threads.
  • Set threadBindings.spawnAcpSessions: true to allow /acp spawn --thread auto|here to bind ACP sessions to Matrix threads.

​
Reactions

Matrix supports outbound reaction actions, inbound reaction notifications, and inbound ack reactions.
  • Outbound reaction tooling is gated by channels["matrix"].actions.reactions.
  • react adds a reaction to a specific Matrix event.
  • reactions lists the current reaction summary for a specific Matrix event.
  • emoji="" removes the bot account’s own reactions on that event.
  • remove: true removes only the specified emoji reaction from the bot account.
Ack reactions use the standard Pllan resolution order:
  • channels["matrix"].accounts.<accountId>.ackReaction
  • channels["matrix"].ackReaction
  • messages.ackReaction
  • agent identity emoji fallback
Ack reaction scope resolves in this order:
  • channels["matrix"].accounts.<accountId>.ackReactionScope
  • channels["matrix"].ackReactionScope
  • messages.ackReactionScope
Reaction notification mode resolves in this order:
  • channels["matrix"].accounts.<accountId>.reactionNotifications
  • channels["matrix"].reactionNotifications
  • default: own
Current behavior:
  • reactionNotifications: "own" forwards added m.reaction events when they target bot-authored Matrix messages.
  • reactionNotifications: "off" disables reaction system events.
  • Reaction removals are still not synthesized into system events because Matrix surfaces those as redactions, not as standalone m.reaction removals.

​
DM and room policy example

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
See Groups for mention-gating and allowlist behavior. Pairing example for Matrix DMs: 
pllan pairing list matrix
pllan pairing approve matrix <CODE>
If an unapproved Matrix user keeps messaging you before approval, Pllan reuses the same pending pairing code and may send a reminder reply again after a short cooldown instead of minting a new code. See Pairing for the shared DM pairing flow and storage layout.

​
Multi-account example

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
          },
        },
      },
    },
  },
}
Top-level channels.matrix values act as defaults for named accounts unless an account overrides them. Set defaultAccount when you want Pllan to prefer one named Matrix account for implicit routing, probing, and CLI operations. If you configure multiple named accounts, set defaultAccount or pass --account <id> for CLI commands that rely on implicit account selection. Pass --account <id> to pllan matrix verify ... and pllan matrix devices ... when you want to override that implicit selection for one command.

​
Private/LAN homeservers

By default, Pllan blocks private/internal Matrix homeservers for SSRF protection unless you explicitly opt in per account. If your homeserver runs on localhost, a LAN/Tailscale IP, or an internal hostname, enable allowPrivateNetwork for that Matrix account: 
{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}
CLI setup example: 
pllan matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx
This opt-in only allows trusted private/internal targets. Public cleartext homeservers such as http://matrix.example.org:8008 remain blocked. Prefer https:// whenever possible.

​
Target resolution

Matrix accepts these target forms anywhere Pllan asks you for a room or user target:
  • Users: @user:server, user:@user:server, or matrix:user:@user:server
  • Rooms: !room:server, room:!room:server, or matrix:room:!room:server
  • Aliases: #alias:server, channel:#alias:server, or matrix:channel:#alias:server
Live directory lookup uses the logged-in Matrix account:
  • User lookups query the Matrix user directory on that homeserver.
  • Room lookups accept explicit room IDs and aliases directly, then fall back to searching joined room names for that account.
  • Joined-room name lookup is best-effort. If a room name cannot be resolved to an ID or alias, it is ignored by runtime allowlist resolution.

​
Configuration reference

  • enabled: enable or disable the channel.
  • name: optional label for the account.
  • defaultAccount: preferred account ID when multiple Matrix accounts are configured.
  • homeserver: homeserver URL, for example https://matrix.example.org.
  • allowPrivateNetwork: allow this Matrix account to connect to private/internal homeservers. Enable this when the homeserver resolves to localhost, a LAN/Tailscale IP, or an internal host such as matrix-synapse.
  • userId: full Matrix user ID, for example @bot:example.org.
  • accessToken: access token for token-based auth.
  • password: password for password-based login.
  • deviceId: explicit Matrix device ID.
  • deviceName: device display name for password login.
  • avatarUrl: stored self-avatar URL for profile sync and set-profile updates.
  • initialSyncLimit: startup sync event limit.
  • encryption: enable E2EE.
  • allowlistOnly: force allowlist-only behavior for DMs and rooms.
  • groupPolicy: open, allowlist, or disabled.
  • groupAllowFrom: allowlist of user IDs for room traffic.
  • groupAllowFrom entries should be full Matrix user IDs. Unresolved names are ignored at runtime.
  • replyToMode: off, first, or all.
  • threadReplies: off, inbound, or always.
  • threadBindings: per-channel overrides for thread-bound session routing and lifecycle.
  • startupVerification: automatic self-verification request mode on startup (if-unverified, off).
  • startupVerificationCooldownHours: cooldown before retrying automatic startup verification requests.
  • textChunkLimit: outbound message chunk size.
  • chunkMode: length or newline.
  • responsePrefix: optional message prefix for outbound replies.
  • ackReaction: optional ack reaction override for this channel/account.
  • ackReactionScope: optional ack reaction scope override (group-mentions, group-all, direct, all, none, off).
  • reactionNotifications: inbound reaction notification mode (own, off).
  • mediaMaxMb: outbound media size cap in MB.
  • autoJoin: invite auto-join policy (always, allowlist, off). Default: off.
  • autoJoinAllowlist: rooms/aliases allowed when autoJoin is allowlist. Alias entries are resolved to room IDs during invite handling; Pllan does not trust alias state claimed by the invited room.
  • dm: DM policy block (enabled, policy, allowFrom).
  • dm.allowFrom entries should be full Matrix user IDs unless you already resolved them through live directory lookup.
  • accounts: named per-account overrides. Top-level channels.matrix values act as defaults for these entries.
  • groups: per-room policy map. Prefer room IDs or aliases; unresolved room names are ignored at runtime. Session/group identity uses the stable room ID after resolution, while human-readable labels still come from room names.
  • rooms: legacy alias for groups.
  • actions: per-action tool gating (messages, reactions, pins, profile, memberInfo, channelInfo, verification).