Skip to main content

​
Configuration Overview

Gate uses a YAML configuration file to control all proxy settings including server routing, authentication, compression, forwarding modes, and more.

​
Config File Location

Gate looks for config.yml in the current working directory by default. You can specify a custom path: 
# Use default config.yml in current directory
gate

# Use custom config file
gate -c /path/to/config.yml
gate --config /path/to/config.yml

​
Supported Formats

Gate supports multiple configuration formats:
  • YAML - .yml or .yaml (recommended)
  • JSON - .json
  • Environment Variables - Prefix with GATE_
You can mix formats by using a config file and overriding specific values with environment variables.

​
Generating Configuration Files

Gate includes built-in configuration templates. Generate them using: 
# Write to config.yml
gate config --write

# Generate specific template type
gate config --type simple --write
gate config --type lite --write

# Output to custom file
gate config > my-config.yml
gate config --type simple > simple-config.yml

​
Configuration Templates

Gate provides several configuration templates for different use cases:

Simple

Minimal configuration for basic proxy setups with just server routing

Full

Complete configuration with all options and detailed comments (recommended)

Lite

Lightweight reverse proxy mode for hostname-based routing

Bedrock

Cross-play configuration for Java and Bedrock Edition players

​
Basic Configuration Structure

Here’s a minimal working configuration:
config-simple.yml
config:
  # Bind address for incoming connections
  bind: 0.0.0.0:25565
  
  # Online mode (authenticate with Mojang)
  onlineMode: true
  
  # Register backend servers
  servers:
    lobby: localhost:25566
    survival: localhost:25567
    creative: localhost:25568
  
  # Try servers in order on login
  try:
    - lobby
    - survival

​
Complete Configuration Example

A more complete configuration with commonly used options:
config.yml
config:
  # Network settings
  bind: 0.0.0.0:25565
  onlineMode: true
  
  # Backend servers
  servers:
    lobby: localhost:25566
    survival: localhost:25567
    creative: localhost:25568
    minigames: localhost:25569
  
  # Connection order on login/fallback
  try:
    - lobby
    - survival
  
  # Status ping response
  status:
    motd: |
      §bWelcome to My Server
      §fPowered by Gate
    showMaxPlayers: 1000
    favicon: server-icon.png
    logPingRequests: false
  
  # Compression settings
  compression:
    threshold: 256  # Compress packets larger than 256 bytes
    level: -1       # Default compression level
  
  # Player info forwarding
  forwarding:
    mode: velocity
    velocitySecret: your-secret-here
  
  # Timeouts
  connectionTimeout: 5s
  readTimeout: 30s
  
  # Rate limiting
  quota:
    connections:
      enabled: true
      ops: 5
      burst: 10
      maxEntries: 1000

​
Configuration Sections

Gate configuration is organized into logical sections:

​
Core Settings

​
config.bind
string
default:"0.0.0.0:25565"
The address to bind for incoming Minecraft client connections
​
config.onlineMode
boolean
default:"true"
Whether to authenticate players with Mojang’s authentication servers. Set to false for offline/cracked servers (not recommended)
​
config.debug
boolean
default:"false"
Enable debug logging for troubleshooting. Shows detailed packet and connection information

​
Server Configuration

  • servers - Register backend Minecraft servers
  • try - Define server connection order for login and fallback
  • forcedHosts - Route players based on connection hostname

​
Client Connection Settings

  • status - Configure server list ping response (MOTD, favicon, player count)
  • compression - Packet compression settings
  • forwarding - Player info forwarding to backend servers

​
Advanced Features

​
config.acceptTransfers
boolean
default:"false"
Allow players transferred from other hosts via the Transfer packet (Minecraft 1.20.5+)
​
config.bungeePluginChannelEnabled
boolean
default:"true"
Support BungeeCord plugin messaging channels. Disable if backend servers are untrusted
​
config.builtinCommands
boolean
default:"true"
Register built-in proxy commands like /server and /glist
​
config.requireBuiltinCommandPermissions
boolean
default:"false"
Whether players need permissions to execute built-in commands. Enable in production
​
config.announceProxyCommands
boolean
default:"true"
Declare proxy commands to 1.13+ clients for tab completion
​
config.forceKeyAuthentication
boolean
default:"true"
Enforce the public key security standard added in Minecraft 1.19

​
Timeouts

​
config.connectionTimeout
duration
default:"5s"
How long to wait when connecting to a backend server before timing out
​
config.readTimeout
duration
default:"30s"
How long to wait for data from a backend server before timing out. Increase for Forge servers
​
config.failoverOnUnexpectedServerDisconnect
boolean
default:"true"
Attempt to reconnect players to another server when unexpectedly disconnected

​
Security Settings

​
config.onlineModeKickExistingPlayers
boolean
default:"false"
Kick existing players when an online-mode player with the same name joins. Useful for mixed online/offline setups
​
config.proxyProtocol
boolean
default:"false"
Support HAProxy PROXY protocol for incoming connections. Don’t enable unless you know what this is

​
Shutdown Message

​
config.shutdownReason
string
The disconnect message shown to players when the proxy shuts down. Supports both legacy § format and modern JSON text components
shutdownReason: |
  §cGate proxy is shutting down...
  Please reconnect in a moment!

​
Rate Limiting (Quota)

Protect your proxy from connection flooding:
​
config.quota.connections
object
Rate limit new connections per IP block
quota:
  connections:
    enabled: true
    ops: 5           # 5 connections per second
    burst: 10        # Allow bursts up to 10
    maxEntries: 1000 # Track up to 1000 IP blocks
​
config.quota.logins
object
Rate limit login attempts per IP block
quota:
  logins:
    enabled: true
    ops: 0.4         # 0.4 logins per second
    burst: 3         # Allow bursts up to 3
    maxEntries: 1000

​
Query Protocol

Support for GameSpy 4 (Minecraft query protocol) on UDP:
​
config.query.enabled
boolean
default:"false"
Enable query protocol support
​
config.query.port
integer
default:"25577"
UDP port for query protocol
​
config.query.showPlugins
boolean
default:"false"
Show plugin information in query responses
query:
  enabled: true
  port: 25577
  showPlugins: false

​
Authentication

Customize Mojang authentication:
​
config.auth.sessionServerUrl
string
Base URL for Mojang session server. Customize for alternative authentication serversDefault: https://sessionserver.mojang.com/session/minecraft/hasJoined
auth:
  sessionServerUrl: https://example.com/session/minecraft/hasJoined

​
Configuration Validation

Gate validates your configuration on startup and reports:
  • Errors - Critical issues that prevent startup (invalid addresses, unknown forwarding modes)
  • Warnings - Non-critical issues you should be aware of (offline mode, no servers configured)
# Check configuration without starting proxy
gate config --validate

​
Live Config Reload

Gate automatically watches for configuration file changes and reloads when detected. You can also manually reload: 
# In Gate console
/greload

# Via Gate API
curl -X POST http://localhost:8080/reload
Some settings require a full restart:
  • bind address
  • lite.enabled
  • bedrock.enabled
See Configuration Reload for details.

​
Environment Variables

Override configuration with environment variables using the GATE_ prefix: 
# Override bind address
export GATE_CONFIG_BIND="0.0.0.0:25565"

# Set Velocity secret
export GATE_CONFIG_FORWARDING_VELOCITYSECRET="your-secret"

# Enable debug mode
export GATE_CONFIG_DEBUG="true"

gate

​
Best Practices

Always set onlineMode: true in production to verify players with Mojang. Offline mode allows anyone to join with any username.
Configure forwarding to pass real player IPs and UUIDs to backend servers. Use velocity mode for best security.
Enable quota settings to protect against connection floods and login spam attacks.
Choose clear server names like lobby, survival, creative instead of server1, server2.
Increase readTimeout to 60s or more if using Forge/modded servers which can be slow to respond.
Use environment variables for sensitive values like velocitySecret instead of committing them to config files.

​
Next Steps

Servers

Configure backend servers and connection order

Forced Hosts

Route players based on connection hostname

Status Ping

Customize MOTD, favicon, and server list appearance

Forwarding

Set up player info forwarding to backend servers

Build docs developers (and LLMs) love

Get started for freeTalk to us