4FreeForumsFree forum softwareStart a forum

Synapse Worker Architecture: The Key Numbers Breakdown

By 4FreeForums Editors · Published October 31, 2026 · Sources linked below

Synapse Worker Architecture: The Key Numbers Breakdown

When running a Matrix community, Synapse begins as a single monolithic process that handles every task within Python. Small community instances can comfortably rely on this monolithic setup, but as community participation and federation scale, a single process eventually hits performance limits. Synapse resolves these bottlenecks by dividing functionality across separate Python processes known as workers. Because these processes run concurrently while communicating over replication streams, deciding when and how to deploy dedicated worker instances requires reviewing configuration metrics, internal ports, and process architecture. This key-numbers breakdown examines the critical specifications and operational boundaries defined in the official documentation.

1 Shared PostgreSQL Database Instance: Moving Past Monolith Limits

In default monolithic deployments, Synapse executes all operations in a solitary process. While SQLite is available for demo installations, the documentation makes clear that workers only operate with PostgreSQL-based deployments. Any community administrator contemplating the shift to worker instances must already be running PostgreSQL. Regardless of how many worker processes are spawned, all processes continue to share the exact same database instance.

As traffic expands, the single Python monolith encounters execution bottlenecks when handling client traffic, presence updates, and inbound federation transactions simultaneously. Transitioning to workers decouples these tasks into discrete Python processes that scale horizontally. Because every worker establishes its own database connections to the single PostgreSQL host, tracking database connection capacity becomes mandatory before introducing new worker processes.

For related guidance on connection tuning, see our overview of tuning PostgreSQL and connection pooling for Matrix Synapse, as well as our broader Synapse Matrix homeserver profile for decentralized community chat.

Port 9093: Securing the Internal HTTP Replication Listener

Synapse workers coordinate using a dedicated Synapse-specific replication protocol analogous to PostgreSQL or MySQL database replication. This stream feeds newly written data between processes so they stay synchronized with database state. To accept replication traffic from workers, the main process must expose an HTTP replication listener, traditionally configured on port 9093.

According to the Workers documentation from Synapse, the replication listener binds by default to 127.0.0.1. Administrators must heed severe security boundaries around this port:

Port 6379: Redis Coordination and Shared Cache Overhead

A functional worker cluster requires a separate coordination backbone. Synapse relies on a Redis pub/sub channel to distribute the replication stream among all configured processes. Redis also serves as a shared cache alongside its pub/sub responsibilities. Deployments communicate with Redis over its default port 6379.

Before launching worker processes, administrators verify Redis responsiveness by piping a PING command through netcat to localhost on port 6379, ensuring the service replies with +PONG. The main process and each worker establish connections to Redis. This shared pub/sub layer offloads inter-process signaling, allowing processes to notify peers of fresh events without continuous polling.

Port 8083: Process Segregation and HTTP Worker Endpoints

Each worker process requires its own configuration file, specifying a unique worker_name and the worker application type, such as synapse.app.generic_worker. Workers that handle incoming network traffic define dedicated listeners. A standard generic worker example sets an HTTP listener on port 8083 with client and federation resource names.

To distribute traffic effectively across these listening ports, an external reverse proxy such as NGINX or HAProxy is required. The proxy inspects inbound requests and routes specific paths away from the main process toward dedicated worker ports such as port 8083. Endpoints suitable for generic workers include:

Version 1.73: Modernizing Worker Configuration Directives

Tracking the Synapse software release cycle ensures configuration directives remain accurate as worker architecture matures. In Synapse version 1.72 and older, worker configurations handling encryption key uploads via /_matrix/client/v3/keys/upload required an explicit worker_main_http_uri setting. Starting in Synapse version 1.73 and newer, this configuration option is no longer required and is completely ignored by the worker runtime.

Worker processes typically ingest shared configuration settings alongside their specific configuration file. The main process takes all settings directly from the shared file, while worker processes inherit shared directives—such as database access and Redis coordinates—while overriding logging and listener ports.

1 Single Process: Routing Constraints for Sync and SSO

Scaling through horizontal processes introduces operational constraints where traffic must not be naively split across multiple workers:

By assessing these structural requirements and operational ceilings outlined in the Workers documentation from Synapse, administrators can transition smoothly from a strained monolith to a robust worker architecture.

Sources

Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.