Zero-Downtime Updates
Restart Passage while thousands of players are online — nobody notices. Players are connected directly to backend servers, not Passage. Roll out updates, change config, swap instances freely.
Introduction
If you’ve run a Minecraft network on BungeeCord, Waterfall, or Velocity, you know the pain: restarting the proxy disconnects every player, clustering requires synchronized state across instances, packet transcoding breaks chat signing, and every new Minecraft release is a waiting game. Passage eliminates all of that.
What is Passage?
Section titled “What is Passage?”Passage is a stateless Minecraft transfer router. Instead of maintaining persistent connections and transcoding every packet like a traditional proxy, it authenticates players, routes them to the right backend server, and gets out of the way:
- Authenticates the connecting player with Mojang
- Validates their connection and issues an authentication cookie
- Routes them to the appropriate backend server
- Transfers them using Minecraft’s native transfer packet (1.20.5+)
- Disconnects — the player is now directly connected to the backend
No ongoing packet handling. No per-player state. No bottleneck.
Why Passage?
Section titled “Why Passage?”No Packet Transcoding
Passage only handles the login and transfer phase. Game packets flow directly between players and backends, with zero transcoding overhead and no CPU bottleneck as your network grows.
Full Chat Signing
Traditional proxies intercept and modify chat packets, breaking Mojang’s cryptographic signing chain. Because Passage never relays game packets, chat signatures stay intact — no workarounds needed.
Trivial Horizontal Scaling
No shared state means no complex multi-proxy cluster setup. Put a load balancer in front of as many Passage instances as you need. Each one operates independently, with under 5 MB RAM baseline.
Always Current
When Minecraft 1.22 drops, Passage works immediately. Traditional proxies must update to understand every new packet type. Passage only handles the login/configuration phase, which rarely changes.
Fully Customizable
Pluggable adapter system for status, authentication, discovery, and routing. Fixed configs for simple setups, HTTP/gRPC adapters for dynamic logic, and native Kubernetes/Agones integration.
Key Concepts
Section titled “Key Concepts”Transfer Packet
Section titled “Transfer Packet”Passage leverages the Transfer packet introduced in Minecraft 1.20.5. This packet tells the client to connect to a different server address — without the proxy staying in the middle. After transfer, the player’s connection to Passage drops entirely.
Adapters
Section titled “Adapters”Passage uses a flexible adapter system with five categories, each configured per route:
- Status Adapters: Server list response (MOTD, player count, favicon)
- Authentication Adapters: Player identity verification (Mojang, disabled, fixed, gRPC)
- Discovery Adapters: Find available backend servers (fixed, DNS, Agones, gRPC)
- Discovery Action Adapters: Filter and sort the discovered target list
- Localization Adapters: Disconnect message translations
Stateless Design
Section titled “Stateless Design”Passage holds no state after a player transfers. This means:
- No memory overhead per connected player
- Instant recovery from Passage restarts — no sessions to lose
- No split-brain scenarios in multi-instance deployments
Comparison to Traditional Proxies
Section titled “Comparison to Traditional Proxies”| BungeeCord / Velocity | Passage | |
|---|---|---|
| Restart impact | All players disconnected | Nobody notices |
| Memory per player | ~10–50 MB/1000 players | Negligible |
| Chat signing | Broken or workaround required | Preserved natively |
| New MC version | Wait for proxy update | Works immediately |
| Horizontal scaling | Complex shared-state setup | Standard load balancer |
See the full comparison for more detail.
Use Cases
Section titled “Use Cases”Passage is ideal for:
- Existing networks on Velocity/BungeeCord that want zero-downtime deploys and better scalability
- Cloud-native deployments on Kubernetes with dynamic server discovery via Agones or DNS
- High-availability setups where proxy restarts cannot disconnect players
- Networks that need chat signing to work correctly end-to-end
System Requirements
Section titled “System Requirements”- Minecraft client version 1.20.5 or higher (required for the transfer packet)
- Linux, macOS, or Windows server
- Under 5 MB RAM baseline
- Optional: Kubernetes cluster for Agones integration
Ready to get started? Check out the Installation Guide.