Introduction
What Basalt Proxy does, what it is for and when to put it in front of your servers.
Basalt Proxy sits in front of one or more Minecraft Java servers and gives players a single address. It authenticates players, picks a backend for them, relays the game, and can move a player from one backend to another without disconnecting them. It is written in C++23 and ships as one native executable per platform: no Java runtime is needed on the machine that runs it.
It shares its network layer with Basalt Server, but a Basalt Server behind it is optional. A backend can be a vanilla server, Paper, Spigot, Fabric or Basalt Server, as long as the proxy and the backend agree on a forwarding scheme and a protocol version.
What it does#
- Single entry point. One public address (
25565by default) in front of any number of named backends. Players are routed by the hostname they typed, see Backends and routing. - Authentication in one place. With
online-mode = truethe proxy checks every Java player with Mojang, and passes the verified identity to the backend using one of the forwarding schemes. - Moving between servers. A player is moved with the
sendconsole command, by a plugin, or by a backend that uses the BungeeCord plugin channel. From Minecraft 1.20.2 the client reconfigures in place instead of reconnecting. - Version bridging. Clients from 1.8 up to 26.2 can join a 26.3 backend, and 26.3 clients can reach backends from 1.21.5 up to 26.2. See Bedrock and versions.
- Bedrock players. An optional UDP listener lets Bedrock Edition players join a Java backend.
- Lua plugins. Off by default. Plugins add commands, react to player events and move players, see Plugins.
- Protection. Token-bucket admission control per origin address and globally, bounded buffers, timeouts for every stage of a connection. See Operations.
When to use it#
Use a proxy when you run more than one server and want players to share an address, a lobby and a login, or when you want authentication and connection limiting to live on a machine of its own. If you run a single server, you do not need one.
The proxy is a security boundary
When a backend trusts forwarded identities, anyone who can reach the backend directly can claim to be anyone. Pick a signed scheme (basalt or velocity) and keep the backend ports reachable only from the proxy. Details in Forwarding.
How the documentation is organised#
| Page | Covers |
|---|---|
| Installation | Downloading, running, systemd, Docker, updating |
| Configuration | Every key of proxy.toml and plugins.toml |
| Backends and routing | backends.toml, forced hosts, fallback, commands |
| Forwarding | Identity schemes and the matching backend configuration |
| Bedrock and versions | Bedrock listener, client and backend versions |
| Operations | Logging, statistics, hardening, troubleshooting |