synapse-admin: a React console for a Synapse homeserver

A console that checks the Synapse version before you log in

synapse-admin is an administration interface for a Synapse Matrix homeserver, and its very first screen is a compatibility check. The console needs at least Synapse v1.93.0 for all functions to work as expected, and it determines the server version with the request `/_synapse/admin/v1/server_version`. After you type the homeserver URL on the login page, that version appears below the input field. This is a small design decision with a large practical effect. A homeserver running an older Synapse will silently lack admin API endpoints the console expects, and the version line tells you immediately whether the problem is your configuration or the server behind it. The project is built on react-admin, and the repository is written in TypeScript under the Apache 2.0 licence.

Two endpoint prefixes have to be reachable from the browser

The stated prerequisites are not a Node version or a database, they are network paths. You need access to `/_matrix` and `/_synapse/admin`, and the documentation points at the Synapse administration endpoints page for how the reverse proxy has to be arranged. The reason this matters is architectural: the console is a static frontend that talks to the homeserver directly from the browser, so the browser, not a server-side proxy, must be able to reach those two prefixes. The documentation is explicit that there is no need to expose these endpoints to the internet, but only to your network, and the hosted GitHub Pages deployment carries a warning that the admin endpoints have to be accessible to your browser for the deployment to work at all. The consequence for an operator is that a console on a public domain talking to an internal homeserver needs either a reachable internal hostname for the operator, or a reverse proxy in front of the homeserver that forwards the admin prefix.

Three install routes, and the container is the smoothest

The project documents three ways in. The first is to download the tarball from the latest release, unpack it, and move or symlink the `synapse-admin-x.x.x` directory into the vhost root of any webserver that can serve static files, such as nginx or apache. The second is to run it from source, and the sequence is short:

git clone https://github.com/Awesome-Technologies/synapse-admin.git
cd synapse-admin
yarn install
yarn start

The third is the container, and it is a single command:

docker run -p 8080:80 awesometechnologies/synapse-admin

After that you browse to http://localhost:8080. The repository also ships a `docker-compose.yml` you can bring up with `docker-compose up -d`, and that file is more than a convenience. It defines a `synapse` service on `matrixdotorg/synapse:v1.141.0` with a healthcheck against `http://127.0.0.1:8008/_matrix/client/versions`, and the synapse-admin service depends on it with `condition: service_healthy`, so the console waits until the homeserver answers before it starts. That file is also a working reference for a homeserver on your own machine.

A Raspberry Pi build fails without a Node memory cap

The compose file and the README both carry the same warning, and it is the kind of detail that costs an afternoon if you miss it. If you are building on an architecture other than amd64, for example a Raspberry Pi, you have to define a maximum RAM for node, otherwise the build will fail. The compose file carries the setting as a commented build argument:

#    - NODE_OPTIONS="--max_old_space_size=1024"

The Dockerfile shows why. The build stage is `FROM node:lts`, and it runs `yarn install --immutable --network-timeout=300000` followed by `yarn build --base=$BASE_PATH`, so the entire production bundle is compiled by Node inside the image. A single-threaded ARM board with the default V8 heap limit will run out of memory during that compile, and the failure surfaces as a build error rather than as a runtime problem, which makes it easy to misdiagnose as a network or registry fault. The runtime stage is `nginx:stable-alpine` with the built `dist` directory symlinked into the document root, so the memory pressure is entirely in the builder, not in the served app.

The path prefix is frozen at build time

Serving the console under a subpath is a build-time decision, and this is a real constraint rather than a preference. The path prefix where synapse-admin is served can only be changed during the build step. From source, that means `yarn build --base=/my-prefix`, which is the same flag the Dockerfile passes as `BASE_PATH` and turns into `yarn build --base=$BASE_PATH`. For the prebuilt container the project is blunt: the path cannot be changed directly, so use a reverse proxy instead, and if you want to serve several applications under different paths on one domain you need a reverse proxy anyway. The README then gives a Traefik example, with a router rule matching a host and a `PathPrefix(`/admin`)`, a redirect middleware normalising the trailing slash, and a `stripprefix` middleware removing the prefix. The same approach is what lets you put the console behind an existing domain without giving it its own hostname.

config.json pins which homeservers the console will talk to

By default the operator types the homeserver URL into the login form, which means anyone with the URL can point the console at any server they like. The `config.json` file closes that off. It takes a `restrictBaseUrl` key that accepts either a single server or a list:

{
  "restrictBaseUrl": ["https://your-first-matrix-server.example.com", "https://your-second-matrix-server.example.com"]
}

Once set, the login form no longer lets the user define the homeserver. The file is injected into the container with a bind mount, and the compose snippet is explicit that the mount is read-only:

volumes:
  - ./config.json:/app/config.json:ro

The container also has a healthcheck that fetches `http://127.0.0.1/config.json`, which is a neat way to confirm the mount landed in the right place. The `BASE_PATH` build argument in the compose file is likewise a build-time setting rather than a runtime one, which is the same build-time freeze described above.

Where the console stops, and what it does not do

synapse-admin is a user interface for the Synapse administration API, and that boundary defines its limits. It does not manage the homeserver itself, it does not stand in for a Matrix client, and it has nothing to say about federation or the event store. It also does not configure Synapse: the `homeserver.yaml` in the compose example is a Synapse configuration file with its own environment variables, including `SYNAPSE_CONFIG_PATH` and `SYNAPSE_SERVER_NAME`, and the console never touches it. Another limit is the language. The dependency list shows `ra-language-english`, `ra-language-french` and `ra-language-farsi` alongside `ra-i18n-polyglot`, so the interface ships with a small set of translations rather than the wide localisation a public-facing service would want. The project is not archived and the last push was on 2026-09-17, with releases 0.11.4, 0.11.3 and 0.11.2 all landing in the first week of March 2026, so maintenance is current.

Editorial conclusion

Adopt synapse-admin when you operate a Synapse homeserver and want a browser console for users, rooms and reports instead of curl calls against the admin API, and when you can keep the admin endpoints on your internal network. Skip it if you use a homeserver that is not Synapse, or if you need a versioned, reviewable configuration workflow, since this console is an interactive tool against live server state. Before deploying, check that the homeserver reports at least Synapse v1.93.0, that the `/_matrix` and `/_synapse/admin` endpoints are reachable from the browser, and that the path prefix is fixed at build time with `yarn build --base=/my-prefix` because it cannot be changed in the prebuilt container.

Frequently asked questions

Official sources

1. Awesome-Technologies/synapse-admin on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases