Skip to content

Configuration

Jump to bottom
Fed43 edited this page Oct 10, 2026 · 1 revision

Configuration

MineAlphaProxy is configured through a single YAML file: core.yml. It is created automatically on first launch from a built-in template.

Location

minecraft-proxy/
+-- core.yml              <- main config
+-- forwarding.secret     <- modern forwarding secret (auto-generated)
+-- lang/                 <- language files
+-- VelocityPlugins/      <- Velocity plugins
+-- MineAlphaPlugins/     <- MineAlpha plugins

Never delete core.yml while the proxy is running.

Full Reference

Top-level options

# Proxy brand.
# Allowed values: Fed43Proxy, MineAlphaProxy
proxy-name: "MineAlphaProxy"

# Language code. Files are located in lang/<code>.yml
language: "en"
Key Type Default Description
proxy-name string MineAlphaProxy Proxy brand name. Allowed values: Fed43Proxy, MineAlphaProxy
language string en Language code for player-facing messages. Files live in lang/

bind - network settings

bind:
  host: "0.0.0.0"
  port: 25577
  motd: "§a%proxy_name% §7| §eWelcome!"
  max-players: 500
  online-mode: true
Key Type Default Description
bind.host string 0.0.0.0 Bind address. Use 0.0.0.0 to listen on all interfaces
bind.port int 25577 Port the proxy listens on
bind.motd string MOTD shown in the server list. Supports %proxy_name% placeholder and legacy § color codes
bind.max-players int 500 Max players displayed in the server list. Actual cap is not enforced
bind.online-mode bool true If true, the proxy verifies clients with Mojang. If false, offline UUIDs are used

forwarding - player data forwarding

forwarding:
  mode: "modern"
  secret-file: "forwarding.secret"
Key Type Default Description
forwarding.mode string modern One of: none, legacy, modern
forwarding.secret-file string forwarding.secret File containing the shared secret for modern forwarding

Modes:

  • none - No forwarding. Backend sees the proxy IP and offline UUIDs
  • legacy - BungeeCord-compatible ip_forward. For Minecraft 1.12 and lower
  • modern - Velocity modern forwarding. Required for 1.13+

If modern is set and the secret file is missing, MineAlphaProxy generates one automatically.

servers - backend server list

servers:
  list:
    lobby: "127.0.0.1:25566"
    survival: "127.0.0.1:25567"
  try-order:
    - lobby
    - survival
Key Type Description
servers.list map Each entry is name: "host:port"
servers.try-order list Order in which servers are tried when a player joins

The servers.list map keys are used in other settings like default-server and in commands such as /server <name>.

default-server

default-server: "lobby"

The server a player is sent to after a successful login. Must exist in servers.list.

advanced - fine-tuning

advanced:
  compression-threshold: 256
  compression-level: 6
  read-timeout: 30000
  proxy-protocol: false
  login-ratelimit: 3000
Key Type Default Description
advanced.compression-threshold int 256 Minimum packet size (bytes) to compress. -1 disables compression
advanced.compression-level int 6 zlib compression level. -1 = default
advanced.read-timeout int 30000 Idle timeout in milliseconds
advanced.proxy-protocol bool false Enable HAProxy PROXY protocol support
advanced.login-ratelimit int 3000 Minimum milliseconds between two login attempts from the same IP

query - GameSpy4 query

query:
  enabled: false
  port: 25577
Key Type Default Description
query.enabled bool false Enable GameSpy4 query protocol
query.port int 25577 Port for the query protocol

plugins - plugin folders

plugins:
  velocity-dir: "VelocityPlugins"
  bungee-dir: "BungeePlugins"
Key Type Default Description
plugins.velocity-dir string VelocityPlugins Folder scanned for Velocity plugins
plugins.bungee-dir string BungeePlugins Reserved for BungeeCord plugin support

The MineAlpha plugin folder (MineAlphaPlugins/) is fixed and cannot be changed through core.yml.

Complete Example

Here is a complete core.yml with sensible defaults:

# ============================================
#  MineAlphaProxy - main configuration
#  Format: YAML
# ============================================

proxy-name: "MineAlphaProxy"
language: "en"

bind:
  host: "0.0.0.0"
  port: 25577
  motd: "§a%proxy_name% §7| §eWelcome!"
  max-players: 500
  online-mode: true

forwarding:
  mode: "modern"
  secret-file: "forwarding.secret"

servers:
  list:
    lobby: "127.0.0.1:25566"
    survival: "127.0.0.1:25567"
  try-order:
    - lobby
    - survival

default-server: "lobby"

advanced:
  compression-threshold: 256
  compression-level: 6
  read-timeout: 30000
  proxy-protocol: false
  login-ratelimit: 3000

query:
  enabled: false
  port: 25577

plugins:
  velocity-dir: "VelocityPlugins"
  bungee-dir: "BungeePlugins"

Import from Existing Proxies

On the first launch, if core.yml does not exist yet and one of these files is present, MineAlphaProxy will import its settings automatically:

File present Imported from
velocity.toml Velocity configuration
config.yml BungeeCord configuration

After import, the file is saved as core.yml. You can then delete the original or leave it - it will be ignored on subsequent launches.

What is imported from Velocity

  • bind → bind.host + bind.port
  • motd → bind.motd
  • show-max-players → bind.max-players
  • online-mode → bind.online-mode
  • [servers] → servers.list + servers.try-order
  • player-info-forwarding-mode → forwarding.mode
  • forwarding-secret-file → forwarding.secret-file
  • [advanced] → advanced.*
  • [query] → query.*

Fields that are not imported: forced-hosts, ping-passthrough.

Reloading the Config

While the proxy is running, the config can be reloaded from the console:

reload

This reloads core.yml and the language files. Changes to bind.host, bind.port, servers.list, and plugins.* require a full restart.

Validation

On startup, MineAlphaProxy validates the config and refuses to start on errors:

  • proxy-name must be one of the allowed values
  • bind.port must be in the range 1..65535
  • servers.list must not be empty
  • default-server must exist in servers.list
  • If forwarding.mode is modern, the secret file must exist

Example error:

Invalid proxy-name: 'MyProxy'. Allowed values: [Fed43Proxy, MineAlphaProxy]

Fix the value in core.yml and restart.

Environment Overrides

Some values can be overridden through environment variables or JVM flags - useful for Docker deployments. This feature is not yet implemented in 1.0.1-ALPHA and is planned for a future release.

Next Steps

Clone this wiki locally