Skip to content

Installation

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

Installation

This page walks you through installing MineAlphaProxy from scratch.

Requirements

Component Minimum Recommended
Java 21 21 LTS (Temurin)
RAM 2 GB 4 GB+
Disk 500 MB 2 GB+
OS Windows 10 / Ubuntu 20.04 / macOS 11 Windows Server 2022 / Ubuntu 22.04

Download Java 21

If you do not have Java 21 installed:

sudo apt update
sudo apt install openjdk-21-jre-headless

Verify installation:

java -version

Expected output:

openjdk version "21.x.x"

Download MineAlphaProxy

  1. Open the Releases page
  2. Find the latest version (for example, v1.0.1-alpha)
  3. Download MineAlphaProxy-1.0.1-ALPHA.jar

Note: If the release does not include a JAR (because it is too large), build it yourself - see the next section.

Building from Source

If you prefer to build the JAR yourself:

git clone https://github.com/MineAlphaStudio/MineAlphaProxy.git
cd MineAlphaProxy
./gradlew clean build

Output:

build/libs/MineAlphaProxy-1.0.1-ALPHA.jar

Optional: Enabling built-in ViaProxy

ViaProxy is bundled inside the JAR as a resource. Before building, place the ViaProxy JAR here:

libs/ViaProxy.jar

Download it from: https://github.com/ViaVersion/ViaProxy/releases

If this file is missing, MineAlphaProxy still builds and runs - just without multi-version support.

First Launch

Create a folder for the proxy and put the JAR inside:

mkdir minecraft-proxy
cd minecraft-proxy
copy D:\Downloads\MineAlphaProxy-1.0.1-ALPHA.jar .

Start the proxy:

java -jar MineAlphaProxy-1.0.1-ALPHA.jar

On Windows

Create run.bat in the same folder:

@echo off
chcp 65001 >nul
java -Dfile.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -jar MineAlphaProxy-1.0.1-ALPHA.jar
pause

Double-click run.bat to start.

On Linux

Create run.sh:

#!/bin/bash
java -Dfile.encoding=UTF-8 -jar MineAlphaProxy-1.0.1-ALPHA.jar

Make it executable:

chmod +x run.sh
./run.sh

What Happens on First Run

The proxy creates several files and folders automatically:

minecraft-proxy/
+-- MineAlphaProxy-1.0.1-ALPHA.jar    <- the JAR
+-- run.bat / run.sh                   <- startup script
+-- core.yml                           <- main config (auto-created)
+-- forwarding.secret                  <- modern forwarding secret (auto-created)
+-- lang/                              <- translations
|   +-- en.yml
|   +-- ru.yml
+-- VelocityPlugins/                   <- Velocity plugins folder
+-- MineAlphaPlugins/                  <- MineAlpha plugins folder

And it prints something like this to the console:

[..] INFO  c.m.MineAlphaProxy - Loading config from core.yml
[..] INFO  c.m.MineAlphaProxy - Using existing forwarding secret: forwarding.secret
[..] INFO  c.m.MineAlphaProxy - Loaded language: ru
[..] INFO  c.m.MineAlphaProxy - [MineAlphaProxy] MineAlphaProxy v1.0.1-ALPHA started on 0.0.0.0:25577
[..] INFO  c.m.MineAlphaProxy - [MineAlphaProxy] MOTD: MineAlphaProxy | Welcome!
[..] INFO  c.m.MineAlphaProxy - Network server bound to 0.0.0.0:25577

The proxy is now running and listening on port 25577.

Connecting a Client

By default, MineAlphaProxy runs on port 25577. Clients must be on the same version as the backend server.

To accept clients from any version (1.7.2 - 26.3), connect through the built-in ViaProxy on port 25576.

For a full version-support setup, see: ViaProxy.

Folder Overview

Folder Purpose
lang/ Language files for messages shown to players
VelocityPlugins/ Drop-in folder for existing Velocity plugins
MineAlphaPlugins/ Drop-in folder for MineAlpha plugins

Never delete core.yml or forwarding.secret while the proxy is running.

Stopping the Proxy

  • Graceful stop: type stop in the console and press Enter
  • Windows: close the console window and press Ctrl+C
  • Linux: press Ctrl+C in the terminal

The proxy will save config, disable plugins, and exit cleanly.

Next Steps

  1. Configure core.yml - set up servers, MOTD, port
  2. Modern Forwarding - connect to Paper backends
  3. Console Commands - useful commands
  4. Writing Plugins - create your own plugin

Common Issues

"Error: Could not find or load main class .encoding=UTF-8"

You are running Java from PowerShell. PowerShell splits the -D arguments incorrectly. Use run.bat on Windows, or quote arguments:

java "-Dfile.encoding=UTF-8" -jar MineAlphaProxy-1.0.1-ALPHA.jar

"Address already in use"

Port 25577 is taken by another process. Either stop the other process or change the port in core.yml:

bind:
  port: 25578

Console shows ??? or box characters

Wrong terminal encoding. On Windows, use run.bat (it runs chcp 65001). On Linux, check LANG:

export LANG=en_US.UTF-8

See Troubleshooting for more.

Clone this wiki locally