Skip to content

ViaProxy

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

ViaProxy

MineAlphaProxy ships with ViaProxy bundled inside the JAR. This lets clients from 1.7.2 to 26.3 connect, while your backend servers can stay on a single version.

What Is ViaProxy

ViaProxy is a standalone translator that accepts connections from clients on any Minecraft version, converts the packets, and forwards them to a target server. It is built on top of ViaVersion, ViaBackwards and ViaRewind.

MineAlphaProxy runs ViaProxy as a child process:

Client (any version)
        |
        v
  ViaProxy  :25576
        |
        v
MineAlphaProxy  :25577
        |
        v
  Backend (single version)

Clients connect to port 25576. MineAlphaProxy handles the proxy logic on port 25577.

How It Works

  1. On startup, MineAlphaProxy extracts the embedded ViaProxy.bin from its JAR to %TEMP%\minealpha-viaproxy\
  2. It writes a viaproxy.yml config with the correct ports
  3. It launches java -jar ViaProxy.jar config viaproxy.yml as a child process
  4. ViaProxy binds to port 25576 and forwards to 127.0.0.1:25577
  5. When MineAlphaProxy stops, ViaProxy is terminated automatically

Requirements

  • Java 21+ - same as MineAlphaProxy
  • 10-30 MB extra disk space in %TEMP% for the extracted ViaProxy
  • No additional downloads - ViaProxy is already inside the MineAlphaProxy JAR

Starting It

Nothing special - just start MineAlphaProxy as usual:

> run.bat
[..] INFO - Network server bound to 0.0.0.0:25577
[..] INFO - Extracted ViaProxy to C:\Users\...\Temp\minealpha-viaproxy\ViaProxy.jar
[..] INFO - ViaProxy started: bind 25576 -> target 25577
[..] INFO - ViaProxy log: C:\Users\...\Temp\minealpha-viaproxy\viaproxy.log

ViaProxy runs in the background. Its output goes to viaproxy.log, not to the console - this keeps the console clean for MineAlphaProxy commands.

Client Connection

Purpose Address
Any version (1.7.2 - 26.3) your_ip:25576
Same version as backend only your_ip:25577

Tell your players to connect to port 25576. That is the recommended setup.

Backend Requirement

Your backend server must run 1.20.2 or newer if you want to support all client versions. ViaProxy translates clients, not backends.

If the backend runs an older version, some features may not work. See the ViaVersion compatibility matrix.

Supported Versions

MineAlphaProxy's bundled ViaProxy supports these client versions out of the box:

Era Versions
Classic 1.7.2 - 1.7.10
Modern 1.8 - 1.12.2
Aquatic 1.13 - 1.13.2
Village 1.14 - 1.14.4
Bee 1.15 - 1.15.2
Nether 1.16 - 1.16.5
Caves 1.17 - 1.18.2
Wild 1.19 - 1.20.6
Tricky 1.21 - 1.21.5
Latest 1.21.6 - 26.3

Bedrock clients are also supported through ViaBedrock - they get a Java account translated on the fly.

Logs

ViaProxy writes its output to a file:

%TEMP%\minealpha-viaproxy\viaproxy.log

View the last 50 lines:

Get-Content "$env:TEMP\minealpha-viaproxy\viaproxy.log" -Tail 50

Follow it live (PowerShell):

Get-Content "$env:TEMP\minealpha-viaproxy\viaproxy.log" -Wait -Tail 20

Typical startup output:

[main/INFO] (ViaProxy) Initializing ViaProxy CLI v3.4.14
[main/INFO] (ViaProxy) Using java version: Java 21.0.12
[main/INFO] (ViaVersion) ViaVersion detected lowest supported version by the proxy: 1.7.2-1.7.5 (4)
[main/INFO] (ViaVersion) Highest supported version by the proxy: 26.3 (777)
[main/INFO] (ViaProxy) ViaProxy started successfully!
[main/INFO] (ViaProxy) Binding proxy server to 0.0.0.0:25576

Configuration

ViaProxy is configured through a generated viaproxy.yml written on every launch:

bind-address: 0.0.0.0:25576
target-address: 127.0.0.1:25577
target-version: auto
server-icon: false
legacy-passthrough: true
Key Description
bind-address Address and port ViaProxy listens on
target-address Where to forward traffic - always MineAlphaProxy
target-version auto detects the backend version; set explicitly if auto-detection fails
server-icon Show the backend's icon in the server list
legacy-passthrough Allow 1.6 and older clients

The file is rewritten on each launch. To change settings, edit ViaProxyLauncher.java in the source and rebuild.

Disabling ViaProxy

If you do not need multi-version support, ViaProxy is simply not started when the embedded resource is missing.

To disable in a build:

  1. Remove libs/ViaProxy.jar
  2. Rebuild: ./gradlew clean build

The proxy will start without ViaProxy and print:

WARN c.m.c.viaproxy.ViaProxyLauncher - Embedded ViaProxy.bin not found - Via disabled

Clients must then match the backend version exactly.

Troubleshooting

"Invalid target server version. Defaulting to auto detect."

ViaProxy could not determine the backend's version from target-version. This is a warning, not an error - it will auto-detect on the first client connection.

To silence it, set target-version to an exact value. In ViaProxyLauncher.java:

String yaml =
        "bind-address: 0.0.0.0:" + bindPort + "\n" +
        "target-address: 127.0.0.1:" + targetPort + "\n" +
        "target-version: 1.21.4\n" +   // <- exact version here
        "server-icon: false\n" +
        "legacy-passthrough: true\n";

Rebuild and restart.

"Address already in use" on port 25576

Another process is using port 25576. Common causes:

  • A previous ViaProxy process did not shut down
  • Another proxy (BungeeCord, Velocity) is running

Check on Windows:

netstat -ano | findstr :25576

Kill the process by PID:

taskkill /PID <pid> /F

ViaProxy starts but clients cannot connect

Check:

  1. Firewall allows inbound on port 25576
  2. target-address points to 127.0.0.1:25577 (default)
  3. MineAlphaProxy is actually running on port 25577

View the ViaProxy log for connection attempts:

Get-Content "$env:TEMP\minealpha-viaproxy\viaproxy.log" -Tail 100

ViaProxy crashes on startup

Check the log file for exceptions. Common cause: Java version too old. ViaProxy 3.x requires Java 21+.

Verify:

java -version

Client sees "Outdated server" or "Outdated client"

ViaProxy is not running, or the client is on a version older than 1.7.2.

Make sure the client connects to port 25576, not 25577.

How to Update ViaProxy

When a new ViaProxy release is out:

  1. Download ViaProxy-x.y.z.jar from https://github.com/ViaVersion/ViaProxy/releases
  2. Replace libs/ViaProxy.jar in the source
  3. Rebuild: ./gradlew clean build
  4. Delete %TEMP%\minealpha-viaproxy\ so the new version is extracted on next launch

Security Notes

  • ViaProxy translates packets - it does not bypass authentication
  • Premium players are still verified by Mojang
  • Cracked players still get offline UUIDs
  • Modern forwarding (see Modern-Forwarding) still secures the proxy-to-backend link

Next Steps

Clone this wiki locally