Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Maven Central Maven Central (snapshot) Codecov


JVM Platform Status
OpenJDK (Temurin) Current Linux Build (OpenJDK (Temurin) Current, Linux)
OpenJDK (Temurin) LTS Linux Build (OpenJDK (Temurin) LTS, Linux)
OpenJDK (Temurin) Current Windows Build (OpenJDK (Temurin) Current, Windows)
OpenJDK (Temurin) LTS Windows Build (OpenJDK (Temurin) LTS, Windows)


  • Token-based invitations for Matrix homeservers.
  • Written in pure Java 17.
  • OSGi ready
  • JPMS ready
  • ISC license
  • High-coverage automated test suite


The portero package only works with the Synapse homeserver at present. Support for other servers is conditional upon them adding a usable API for registering users with public registration disabled.


The portero package is designed to be deployed onto the same server as the Matrix homeserver, behind a reverse proxy such as nginx. It consists of a server process that listens on a public port P and a private port Q. The server presents a friendly user-facing set of pages via P, and an API with which adminstrators are expected to interact via Q.

$ portero server --configuration-file server.conf
INFO com.io7m.portero.server.internal.PServerMain: private server starting on /
INFO com.io7m.portero.server.internal.PServerMain: public server starting on /

The portero server command stays running in the foreground and is designed to execute under a process supervision system such as runit.

Administrators send invite requests to Q, and an invite token is returned to the administrator:

$ portero invite --configuration-file server.conf

The returned URL can then be sent to a user, and the user can visit the provided URL and be taken through a simple web form in order to create an account. The portero server serves the web form on P and therefore needs to be made accessible to the outside world over a secure connection. The portero server then creates an account on the Matrix homeserver using the Synapse-specific Admin API.


Configuration File

# The registration shared secret on the Matrix homeserver.
matrix.adminSharedSecret = aRatherLongSharedSecret

# The URL by which the portero server speaks to the Matrix homeserver.
# It is recommended that the portero server should run on the same
# host as the homeserver, and should speak to the homeserver over localhost.
matrix.adminURL =

# The public URL to which users will be redirected when they successfully
# sign up for an account.
matrix.publicURL =

# The address and port to which the private server will bind.
server.privateAddress =
server.privatePort = 20001

# The address and port to which the public server will bind.
server.publicAddress =
server.publicPort = 20000

# The base URL that will be used in invite requests. The portero public
# server should be accessible to the outside world using this URL.
server.publicURL =

# The title of the Matrix homeserver to be used on invitation pages.
server.title =

# The number of server threads. This is equivalent to the number of users
# that can be served concurrently.
server.threadCount = 4

# The expiry duration for tokens, ISO 8601 duration format.
server.tokenExpiration = PT48H


$ portero

      Set the minimum logging verbosity level.
      Default: info
      Possible Values: [trace, debug, info, warn, error]

  Use the "help" command to examine specific commands:

    $ portero help help.

  Command-line arguments can be placed one per line into a file, and the file
  can be referenced using the @ symbol:

    $ echo help > file.txt
    $ echo help >> file.txt
    $ portero @file.txt

    help        Show detailed help messages for commands.
    invite      Create an invite URL
    server      Start an invite server
    version     Show the application version.



Matrix server registration gatekeeper