Element Server Suite: pipe

26 Jun, 2025

Note: I have ESS, but don’t have Synapse Pro.

Background

Element Server Suite is Element’s proprietary suite for running a Matrix homeserver. It comes with things like an admin panel, integration manager (called Integrator, but I think it’s literally Scalar), and the Secure Border Gateway.

The Admin and Audit bots sit in rooms so that administration and auditing conversations is easier.

pipe is the software behind both. It’s “a flexible pipeline for handling Matrix messages”.

Setting up AdminBot

Before you start: pipe needs Synapse.

First get the container image at registry.element.io/pipe:6.1.2. Credentials are required, but I leave getting them as an exercise to the reader. Pretend I work at Element.

This is pipe’s config. It should be mounted at /data/config.yml:

base:
  name: admin
  config:
    homeservers:
    - domain: "example.com"
      url: "http://localhost:8008"
      adminToken: "<token of an admin user on the server>"
      appserviceDeviceId: "ADMINBOT" # TODO: i had to leave this blank. do i not have MSC3202 in my copy of synapse?
      homeserverToken: "hs_token"
      appserviceToken: "as_token"
      appservicePort: 9995
      botUserId: "@adminbot:example.com"
    options:
      storageDir: "/dir/for/storage"
      backupPassphrase: "key backup passphrase"
      shouldJoinDMs: true
      onlyJoinLocalRooms: true

Then Synapse needs to be configured by adding the appservice and enabling certain MSCs.

adminbot-pipe.yaml:

id: "adminbot-pipe"
url: "http://127.0.0.1:9995"
as_token: "as_token"
hs_token: "hs_token"
rate_limited: false
sender_localpart: 'adminbot-sendernotinuse'
namespaces:
  rooms:
  - exclusive: false
    regex: "!.*:example.com"
  users:
  - exclusive: false
    regex: "@.*:.*"
  - exclusive: true
    regex: "@adminbot:example.com"

de.sorunome.msc2409.push_ephemeral: true
org.matrix.msc3202: true

homeserver.yaml:

app_service_config_files:
  - adminbot-pipe.yaml

# taken from the config templates
experimental_features:
  msc2409_to_device_messages_enabled: true
  msc3202_device_masquerading: true
  msc3202_transaction_extensions: true
  msc3983_appservice_otk_claims: true
  msc3984_appservice_key_query: true

Now you can start pipe! You should see the user of the admin token you provided invite the bot to rooms and make it admin in each one. Even new rooms!

AdminBot controlling a user to make itself admin in their new room.

Extra features

There’s no documentation or source tree for pipe. However, /app/matrix-pipe.js has 462,944 lines of JS to browse through (not all of the code is Element’s, libraries are included)!

From this we can see that it can be more than the admin or audit bots:

// src/config/base/index.ts
function createConfigFromBase5(name, input) {
  if (input.homeservers.length < 1) {
    throw Error("Expected at least one homeserver defined in config");
  }
  switch (name) {
    case "disaster-recovery":
      return createConfigFromBase(getBaseConfig(input));
    case "disaster-recovery-keybackup":
      return createConfigFromBase2(getBaseConfig2(input));
    case "audit":
      return createConfigFromBase3(getBaseConfig3(input), "audit");
    case "admin":
      return createConfigFromBase3(getBaseConfig3(input), "admin");
    case "webhook-service":
      return createConfigFromBase4(getBaseConfig4(input));
    default:
      throw Error(`Unknown base config name '${name}'`);
  }
}

disaster-recovery seems to manage a disaster recovery space on two homeservers, and I don’t know about webhook-service but it’s probably self-explanatory.

I haven’t really looked into these yet, so I may update this post with more info later.

Hopefully I can look at other stuff too in coming posts. Thanks for reading :)