Description

n8n Matrix E2EE

Send and receive messages in encrypted Matrix rooms from n8n.

The gateway connects to Matrix and manages the session and encryption keys. The n8n nodes connect to the gateway so your workflows can listen for activity and interact with rooms:

• Trigger workflows on incoming messages (text, media, and voice), reactions, or room membership changes (invites, joins, and leaves).
• Send and manage messages — text, notices, emotes, images, voice messages, replies, threads, edits, reactions, deletions, and typing indicators.
• Manage rooms — create rooms, join or leave rooms, and invite users.

Getting started

You’ll need a Matrix account, Docker or Podman, and a self-hosted n8n instance.
The gateway image supports Linux AMD64 and ARM64. The commands below use Docker;
replace docker with podman if that’s what you use.

1. Configure the gateway

Save config.toml.example as config.toml and fill in your details:

port = 8080
[default]
homeserver_url = "https://matrix.example.org"
matrix_user = "@n8n-bot:example.org"
matrix_password = "your-bot-password"
apisecrettoken = "your-random-api-token"

You can define multiple [account-name] sections in config.toml with distinct apisecrettoken values to run several Matrix accounts in one gateway instance (string values also support ${VAR} environment variable interpolation). Generate each API token with openssl rand -hex 32. Keep config.toml private.

2. Start the gateway

From the directory containing config.toml, run:

docker run --detach --name n8n-matrix-e2ee-gateway 
  --restart unless-stopped 
  --publish 127.0.0.1:8080:8080 
  --volume ./config.toml:/app/config.toml:ro 
  --volume n8n-matrix-e2ee-data:/app/data 
  ghcr.io/spindle-studio/n8n-matrix-e2ee-gateway:0.4.0

Keep the data volume when upgrading: it stores the Matrix session and encryption
keys. Keep the gateway on a private network and protect its API token.

Check that it has started:

curl --fail http://localhost:8080/healthz

If it isn’t ready, check docker logs n8n-matrix-e2ee-gateway.

3. Connect n8n

In n8n, open Settings > Community Nodes and install
@spindle-studio/n8n-nodes-matrix-e2ee.

Create Matrix E2EE Gateway API credentials with:

• Gateway Base URL: http://localhost:8080 if n8n runs directly on the same host.
• API Token: the account’s apisecrettoken value from config.toml.

If n8n runs in a container, put both containers on a shared network:

docker network create n8n-matrix-e2ee
docker network connect n8n-matrix-e2ee n8n-matrix-e2ee-gateway
docker network connect n8n-matrix-e2ee YOURN8NCONTAINER

Replace YOURN8NCONTAINER with its name, then use
http://n8n-matrix-e2ee-gateway:8080 as the gateway URL. For n8n on another
machine, provide access over a private network; the command above exposes the
port only on the local host.

Test and save the credentials.

4. Receive your first message

Add Matrix E2EE Trigger to a workflow, choose an event such as On Message, select your credentials, and click Listen for test event. Invite the Matrix account to a room (or join one using the Matrix E2EE node) and send a message from another account to see the event arrive in n8n.

The trigger only receives new events while listening—earlier history isn’t replayed, and events sent by the connected account itself are ignored. When receiving images or audio, you can enable Download Media on the trigger to pass the file to later steps.

Compatibility

| n8n package | Gateway |
| — | — |
| 0.3.0 | 0.4.0 or later supporting the same API |

Use a current self-hosted n8n release with Node.js 22.4 or later. The package
has not been verified for n8n Cloud. The gateway and nodes have separate versions;
check release notes before upgrading.

Help and contributions

Open an issue for bugs
or feature requests. For security issues, follow the security policy.
Other enquiries: ben@spindle.studio.

See Contributing to make a change, or the
development guide for local setup, the API, and Matrix device troubleshooting.

This is an independent community project. Licensed under MIT.