Gourd

A lightweight Minecraft proxy built on the Pumpkin protocol library.

Gourd sits between Minecraft clients and Pumpkin backend servers, handling authentication, encryption, and packet forwarding. Players can switch between backend servers without disconnecting.

Features

• Online & offline mode — Full Mojang authentication with RSA encryption, or offline mode for development
• Velocity modern forwarding — Securely forwards player identity to backend servers via HMAC-SHA256
• Server switching — Players use /server <name> to move between backends seamlessly, with tab completion for server names
• Fallback servers — If the default server is down, players connect to the next available backend
• Server switch resilience — Failed switches keep the player on their current server instead of disconnecting
• Fallback server — If the current backend disconnects, players are automatically moved to a configured fallback server
• Backend-initiated transfers — Backend servers can send players to other servers via the gourd:transfer plugin channel
• /send command — Send other players to a server with /send <player> <server>, with tab completion
• Backend health checks — Periodic TCP health probes; /server shows live status per backend
• Player count tracking — Accurate online player count in the server list
• Graceful shutdown — Ctrl+C sends disconnect messages to all players and drains connections before exiting
• Packet compression — Configurable zlib compression threshold
• Rate limiting — Per-IP connection limits and login rate limiting to prevent flooding
• IP bans — Block specific IPs via config
• Whitelist/blacklist — Control player access by username
• Idle timeout — Disconnects inactive connections to prevent slowloris-style attacks
• Hot config reload — Automatically picks up config changes without restart

Building

cargo build --release

Setup

1. Configure Gourd

On first run, Gourd generates a config.toml:

bind = "0.0.0.0:25577"
online_mode = true
motd = "A Gourd Proxy"
max_players = 100
default_server = "lobby"
gourd_secret = "<auto-generated>"
compression_threshold = 256
login_timeout_secs = 30
max_connections_per_ip = 3
login_rate_limit = 10
idle_timeout_secs = 120
debug = false
banned_ips = []
whitelist_enabled = false
whitelist = []
blacklist = []
# fallback_server = "lobby"

[servers.lobby]
address = "127.0.0.1:25565"
motd = "Lobby"

Add more servers under [servers.<name>]:

[servers.survival]
address = "127.0.0.1:25566"
motd = "Survival"

2. Configure backend servers

Each backend needs Velocity modern forwarding enabled with the same secret as gourd_secret.

In the backend's config/features.toml:

[networking.proxy]
enabled = true

[networking.proxy.velocity]
enabled = true
secret = "<same as gourd_secret>"

3. Run

Start your backend servers first, then:

./gourd

Clients connect to Gourd's bind address (default 25577).

Commands

Command	Description
/server	List available servers with health status
/server <name>	Switch to a server (tab completion supported)
/send <player> <server>	Send another player to a server (tab completion supported)

Plugin Channel

Backend servers can trigger player transfers by sending a clientbound Plugin Message (Custom Payload) packet on the gourd:transfer channel. The payload is the target server name as a UTF-8 string. This allows backends to move players between servers programmatically.

Hot Reload

Gourd watches config.toml for changes every 30 seconds. The following fields are reloaded without restart:

• motd, max_players
• servers, default_server, fallback_server
• login_timeout_secs, max_connections_per_ip, login_rate_limit, idle_timeout_secs
• banned_ips, whitelist_enabled, whitelist, blacklist

Changes to bind, online_mode, compression_threshold, gourd_secret, and debug require a restart.