Requirements

What a Bridge network needs: Paper and Velocity, Java 21, packetevents, MongoDB, Redis and the Catalyst backend, and how they connect.

Overview

A Bridge network has three parts:

Paper servers run Bridge, Kernel and Stash through the Aegis loader, plus packetevents.
A Velocity proxy runs Bridge, Kernel and Stash through the Aegis loader.
Catalyst is a separate backend service. It stores ranks, grants, punishments, profiles and network settings in MongoDB and announces every change on Redis.

Bridge on each server talks to Catalyst over HTTP with an API key. Changes reach the other servers through Redis.

What goes where

Product	Paper servers	Velocity proxy	How you get it
Bridge	Yes	Yes	Add it under `products:` in the loader's config.yml.
Kernel	Yes	Yes	Downloaded with Bridge automatically.
Stash	Yes	Yes	Downloaded with Bridge automatically.
packetevents	Yes	No	Install it yourself in `plugins/`.
Toolkit	Yes	No	Add it under `products:`. See Toolkit.
Sentry	Yes	No	Add it under `products:`. See Sentry.

Products that Bridge depends on are delivered and loaded before it, so you only list Bridge, Toolkit and Sentry yourself. packetevents is not delivered by the loader; Bridge and Kernel won't start on Paper without it.

Software versions

Java 21 or newer on every Paper server and the proxy.
Paper 1.21.11. Bridge is built against the Paper 1.21.11 API.
Velocity for the proxy.
MongoDB and Redis that Catalyst and every server can reach.

Catalyst

Catalyst is not a plugin. It is its own service and runs through the Standalone Aegis loader, which needs:

Linux on x86_64.
Java 22 or newer.
Network access to MongoDB and Redis.

See Installation for the Standalone loader. Start Catalyst with:

java --enable-native-access=ALL-UNNAMED -jar Aegis.jar

On first start Catalyst writes config/catalyst.toml next to the loader. It stops again if the configuration is incomplete.

config/catalyst.toml

[server]
bind = "0.0.0.0:8080"
cors_origins = []

[mongo]
uri = "mongodb://127.0.0.1:27017"
database = "catalyst"

[redis]
uri = "redis://127.0.0.1:6379"

[security]
ip_pepper = "CHANGE_ME__set_CATALYST__SECURITY__IP_PEPPER_to_32_or_more_random_bytes"

Environment variables override the file. Use them for secrets:

Variable	What it sets
`CATALYST__MONGO__URI`	MongoDB connection string.
`CATALYST__REDIS__URI`	Redis connection string.
`CATALYST__SECURITY__IP_PEPPER`	A random secret of at least 32 characters. Required. Catalyst refuses to start while the placeholder is still set.
`CATALYST__SECURITY__BOOTSTRAP_KEY`	Your first API key. Required until at least one key exists.

The API key

Every server needs an API key to talk to Catalyst. The simplest setup uses one bootstrap key for everything:

Make up a key in the form cat_<prefix>_<secret>, for example cat_mynet_ followed by a long random string. The prefix must not contain _.
Set it as CATALYST__SECURITY__BOOTSTRAP_KEY and start Catalyst. It logs "Adopted the configured bootstrap API key".
Use the same key as catalystKey on your Paper servers and CATALYST_KEY on the proxy. See Installation.

The bootstrap key has every permission. Catalyst serves an API reference at /docs on its address, which also needs a key. A key with key management rights can issue narrower keys through /v1/keys.

To check Catalyst is up, open /health on its address. It is the only route that needs no key.

Shared Redis

Catalyst announces changes on Redis, and Bridge on each Paper server listens through Stash's Redis connection. Catalyst and Stash must use the same Redis server. If they don't, servers never hear about changes made elsewhere: a new ban won't kick the player from the server they're on, and rank edits, grants and maintenance changes won't reach the other servers.

MongoDB can be shared too. Catalyst keeps its records in its own database (catalyst by default), and Stash uses its own (Scala by default).

Server names and groups

Give every Paper server a unique id, like lobby-1, in serverId of both Bridge's bridge.yml and Kernel's kernel.yml, or set the BRIDGE_SERVER environment variable, which fills both. Use the same name the server has in your proxy's velocity.toml, because /server, /hub, /sendplayer and /jump send players by that name.
Set each server's group in Kernel's kernel.yml (group). Servers in the same group share public chat, the tab list and /list. If you leave it empty, the id without its last part is used, so lobby-1 is in group lobby.

Both settings are covered on Installation.

Next: Installation.