Application Services
Application services are out-of-process programs that extend the homeserver; most bridges (IRC, XMPP, Discord, Telegram, Slack) are implemented this way. They authenticate with a pair of shared secret tokens and declare namespaces of users and room aliases that they manage.
The upstream reference is the Matrix Application Service API specification.
Registration
Tuwunel supports three registration methods. They coexist and are all loaded on startup.
Admin room
The most convenient method for live deployments. Send !admin appservices register to the admin room with the registration YAML in a code block below:
!admin appservices register
\`\`\`
id: my-bridge
url: http://localhost:29328
as_token: secret-token-a
hs_token: secret-token-b
sender_localpart: my-bridge-bot
namespaces:
users:
- exclusive: true
regex: '@my-bridge_.*:example\.com'
\`\`\`
The registration is persisted in the database and survives restarts. Registering with an existing ID replaces the old entry, unless that ID comes from the server configuration or appservice_dir. No restart is required.
Server configuration
Application services can be declared inline in tuwunel.toml. The TOML section key becomes the registration ID unless id is explicitly set:
[global.appservice.my-bridge]
url = "http://localhost:29328"
as_token = "secret-token-a"
hs_token = "secret-token-b"
sender_localpart = "my-bridge-bot"
[[global.appservice.my-bridge.users]]
exclusive = true
regex = '@my-bridge_.*:example\.com'
Config-file registrations are reloaded on each restart. They cannot be removed with !admin appservices unregister.
Registration file directory
Point appservice_dir at a directory containing YAML registration files. Every .yaml or .yml file in it is loaded at startup:
[global]
appservice_dir = "/etc/tuwunel/appservices"
Files use the same YAML format that bridges produce for Synapse. New or removed files are not picked up without a restart.
Unix sockets
On Unix systems, set the registration URL to an absolute socket path:
url: unix:///run/mautrix-whatsapp/appservice.sock
For an inline registration, use the same URL:
[global.appservice.whatsapp]
url = "unix:///run/mautrix-whatsapp/appservice.sock"
Both unix:///absolute/path.sock and unix:/absolute/path.sock are accepted. The path is literal, without percent-decoding; a path prefix after the socket and TLS over the socket are not supported. The bridge may create the socket after tuwunel starts.
For mautrix-go bridges, set appservice.hostname to /run/mautrix-whatsapp/appservice.sock and appservice.address to unix:///run/mautrix-whatsapp/appservice.sock. A leading / in the hostname selects a socket listener, so the port is optional. The bridge copies its address into the generated registration. Mautrix-python bridges listen on TCP only.
The tuwunel process needs write permission on the bridge’s socket file. Run both services as the same user or give tuwunel access through a shared group.
For the reverse direction, set tuwunel’s unix_socket_path to /run/tuwunel/tuwunel.sock and the bridge’s homeserver.address to unix:///run/tuwunel/tuwunel.sock. See the Unix socket configuration and socket activation guide.
Namespaces
Each registration declares which users, room aliases, and room IDs the appservice claims. Entries under users, aliases, and rooms are lists; each entry has a regex and an optional exclusive flag.
| Namespace | Matches | Case |
|---|---|---|
users | User IDs (@localpart:server) | Case-insensitive |
aliases | Room aliases (#alias:server) | Case-insensitive |
rooms | Room IDs (!opaque:server) | Case-sensitive |
A regular expression can match part of an ID or alias. Add ^ at the start and $ at the end if you need to match the full string.
When exclusive: true, the homeserver rejects any attempt by a normal user to register a conflicting user ID or room alias. Multiple appservices can share a non-exclusive namespace; exclusive ranges must not overlap.
Configuration reference
Fields under [global.appservice.<ID>]:
| Field | Default | Description |
|---|---|---|
id | section key | Unique registration ID. Inferred from the TOML section key when omitted. |
url | none | Base URL the homeserver pushes events to, or unix:///absolute/path.sock on Unix. Set to null for receive-only registrations. |
as_token | required | Token the appservice sends to the homeserver in Authorization headers. |
hs_token | required | Token the homeserver sends to the appservice on every push. |
sender_localpart | id | Localpart of the appservice bot user. Defaults to the registration ID. |
rate_limited | false | Whether requests from masqueraded virtual users are rate-limited. The bot user is always exempt. |
protocols | [] | Protocols bridged (e.g. ["irc"]). Reported via the /thirdparty/protocols endpoint. |
receive_ephemeral | false | Include ephemeral events (typing notifications, read receipts) in pushes to the appservice. |
device_management | false | Allow the appservice to manage devices on behalf of virtual users (MSC4190). |
msc3202_transaction_extensions | false | Include end-to-bridge encryption bookkeeping (device-list changes, one-time-key counts, unused fallback key types) in pushes, so encrypting bridges work without a /sync loop (MSC3202, paired with to-device delivery from MSC4203). The registration-file key is org.matrix.msc3202. |
scopes | [] | Permissions the appservice requests, called scopes (MSC4502). The one known scope, urn:matrix:client:io.element.msc4502:rooms:is_joined, lets it ask whether any user or server is joined to a room this server is in. An unknown scope grants no permission. Tuwunel logs it at startup, and !admin appservices register rejects a registration containing one. The registration-file key is io.element.msc4502.scopes. |
proxy_prefix | none | Path prefix the appservice claims (MSC4512). Set to rtc/livekit, the only allowed prefix, together with proxy_url. Only one appservice may claim it. The registration-file key is io.element.msc4512.proxy_prefix. |
proxy_url | none | Base URL that requests under proxy_prefix are forwarded to, or unix:///absolute/path.sock on Unix (MSC4512). The registration-file key is io.element.msc4512.proxy_url. |
With a valid proxy claim, Tuwunel authenticates requests under /_matrix/client/<version>/<prefix> and /_matrix/federation/<version>/<prefix> and forwards them to proxy_url. The appservice may also have Tuwunel sign and send requests to other Matrix servers under that prefix. These server-to-server requests are called federation requests.
At startup, Tuwunel logs and ignores an invalid proxy claim or one another appservice already holds. An otherwise valid registration still loads without the proxy claim. The !admin appservices register command rejects registrations with either problem.
Namespace entries under [[global.appservice.<ID>.users]], aliases, and rooms:
| Field | Default | Description |
|---|---|---|
exclusive | false | Claim exclusive ownership of matching IDs, blocking regular users from registering them. |
regex | required | Regular expression. Unanchored by default. |
Admin commands
All commands run from the admin room (!admin appservices <subcommand>):
| Command | Description |
|---|---|
register | Register or replace an appservice. Paste the YAML in a code block below the command. Config-file registrations cannot be replaced this way. |
unregister <id> | Remove a database-registered appservice and cancel pending deliveries. Config-file registrations cannot be unregistered this way. |
show-config <id> | Print the stored registration as YAML. |
list | List IDs of all loaded appservices. |
Server options
These options go in the top-level [global] section:
| Option | Default | Description |
|---|---|---|
appservice_timeout | 35 | Read and total request timeout in seconds, including socket registrations; connect timeout is 5 seconds. |
appservice_idle_timeout | 300 | Idle connection pool timeout in seconds, including socket registrations. |
dns_passthru_appservices | false | Bypass DNS passthru domain matching for all appservice URLs. More efficient than listing each domain in dns_passthru_domains when all appservices share the same network. Does not apply to socket registrations. |
proxy | none | Outbound HTTP proxy settings do not apply to socket registrations. |
show_appservice_users_in_user_directory | false | Include appservice senders and users in exclusive appservice user namespaces in user directory searches. They remain subject to the normal room visibility rules unless show_all_local_users_in_user_directory is also enabled; Synapse has no equivalent and always hides them. Reloadable. |
Getting help
For setup questions, join #tuwunel:matrix.org or open an issue.