Self-Host Minecraft Java on Proxmox with Localtonet

How the Proxmox, PaperMC, and Localtonet architecture works

This deployment has three separate layers. Proxmox VE provides the virtualization platform, a Debian or Ubuntu guest runs PaperMC, and a Localtonet client establishes the outbound connection used to publish the game server. Keeping those roles separate makes troubleshooting much easier because you can verify each layer before moving to the next one.

Minecraft Java clients communicate with the game server over TCP. The minecraft-server-Proxmox project documents port 25565/TCP for its Java and PaperMC deployment. That is different from the repository's Bedrock workflow, which uses 19132/UDP. This guide intentionally follows the Java path, so the Localtonet configuration must be a TCP tunnel rather than an HTTP or UDP tunnel.

The most reliable setup process is therefore sequential. First, make the VM healthy. Second, install PaperMC and confirm that it listens locally. Third, join it from another device on the LAN if possible. Only after those checks succeed should you introduce the public tunnel. A tunnel cannot repair a game server that failed to start, a VM without network connectivity, or a local firewall rule that blocks the selected target.

Prerequisites and resource planning

The documented minecraft-server-Proxmox requirements are Proxmox VE 7.4 or newer, including the 8.x and 9.x series, and a guest operating system based on Debian 12 or 13 or Ubuntu 22.04 or 24.04. For a Java server, allocate at least 2 virtual CPUs, 2 to 4 GB of RAM, and 10 GB of SSD-backed storage. Actual capacity requirements depend on player count, world size, plugins, view distance, backups, and other workload-specific factors, so treat these values as a starting floor rather than a universal sizing guarantee.

Java 21 is required for current PaperMC builds. The installer attempts to use OpenJDK 21 and falls back to Amazon Corretto 21 through an APT repository with a signed keyring when OpenJDK 21 is unavailable from the guest's configured repositories. You should not plan this deployment around Java 17 because the current project documentation explicitly identifies Java 21 as the minimum.

Before installation, confirm that the guest can resolve DNS names and reach package and download services over the internet. The setup script retrieves software and PaperMC metadata, so an isolated guest without outbound connectivity cannot complete the documented workflow. The VM also needs an address that remains predictable enough for local clients and, if the Localtonet client runs elsewhere, for that client device to reach it.

DHCP is supported by the repository's quick-start path. A DHCP reservation configured on your router or DHCP server is often simpler than editing network configuration inside the guest. The project documentation also provides a static Netplan example, but network interface names, gateway addresses, DNS policies, and subnets vary between installations. Do not copy an example address such as 192.168.1.50 without adapting it to your network and confirming that it is unused.

Prepare the Proxmox virtual machine

Create a new VM through your normal Proxmox administration workflow and install one of the supported guest operating systems. Assign at least 2 vCPU, 2 to 4 GB of RAM, and 10 GB of SSD-backed storage. Connect the VM's virtual network adapter to a bridge that can reach your LAN and the internet, commonly vmbr0.

The exact Proxmox storage pool, firmware mode, disk controller, VLAN tag, bridge configuration, and guest installation procedure depend on your environment. The project evidence does not prescribe universal values for those fields, so this guide does not invent them. Use settings compatible with your existing Proxmox network and storage design.

Update the guest before installing the server

Sign in to the VM and use the package maintenance process appropriate for the selected Debian or Ubuntu release. Confirm that package operations complete without repository, DNS, clock, or disk-space errors. The installer manages the dependencies needed by its own workflow, including the Java 21 fallback when the standard repositories do not provide a suitable package.

Confirm the VM's address

You can inspect the guest's current interfaces and addresses with the standard Linux command below:

ip -br address

Record the address assigned to the bridged interface. You will use it for LAN verification and as the Localtonet target if our client runs on another device. Ignore loopback and container-only interfaces. An address beginning with 127. is local to the VM and cannot be used from another machine.

Decide where the Localtonet client will run

The simplest target relationship is to run our client inside the Minecraft VM. In that arrangement, the client and PaperMC share the same network namespace, so the tunnel can target the game service locally on port 25565. Another valid arrangement is to run the Localtonet client on a separate machine that can reach the VM over the LAN. In that case, the tunnel target must use the VM's reachable LAN address and port 25565.

Avoid assuming that installing the client on the Proxmox host is necessary. It is normally cleaner to keep application software in the guest or on a dedicated management device. Whichever placement you select, verify the local network path before creating the tunnel.

Install PaperMC with minecraft-server-Proxmox

The repository provides setup_minecraft.sh for the VM deployment. It also contains separate installers for LXC and Bedrock, but they are not interchangeable with this workflow. Use the VM script for this guide and run it from inside the guest.

The documented quick start downloads the current script from the repository's main branch, marks it executable, runs it, and then attaches to the Minecraft screen session. Because downloading from a moving branch executes the current version rather than a permanently pinned release, review the script before execution when your change-control process requires it.

wget https://raw.githubusercontent.com/TimInTech/minecraft-server-Proxmox/main/setup_minecraft.sh

chmod +x setup_minecraft.sh

./setup_minecraft.sh

sudo -u minecraft screen -r minecraft

The installer automatically sizes JVM memory from the VM's available RAM. The documented calculation uses an initial heap of approximately one quarter of RAM and a maximum heap of approximately one half of RAM, with the maximum capped at 16 GB. This means increasing VM memory can change the automatically selected JVM allocation, but it does not imply that every workload benefits equally from more memory.

The current project release uses PaperMC's Fill v3 API and filters for builds in the stable channel. It reads download URLs from the API response and performs SHA-256 and size validation. These checks are intended to prevent invalid responses, including HTML error pages, from being treated as a valid server.jar.

Verify the Minecraft server before exposing it

Verification should proceed from the inside out. Start with the server console, then confirm the local listening socket, then test from a Minecraft Java client on the LAN. If all three checks pass, the server side of the deployment is ready for Localtonet.

Check the PaperMC console

Attach to the screen session with the documented command:

sudo -u minecraft screen -r minecraft

Review the output for a completed startup rather than assuming that the presence of a screen session proves the server is ready. Download failures, unsupported Java versions, malformed server files, ownership problems, insufficient memory, and world-loading failures should be resolved before remote-access testing.

If the command reports that no matching screen session exists, do not create a new arbitrary session and assume the installation is repaired. Review the installer's earlier output and the service state in the VM. The repository includes a minecraft.service definition and documents systemd service verification, but exact operational commands can vary if the installation was customized. Use the installed unit and the project's current administration guidance rather than guessing a replacement service name or path.

Confirm that TCP port 25565 is listening

Use the guest's socket inspection tools to check for a listening TCP socket:

ss -ltn

Look for port 25565. A listener bound to all interfaces can normally accept connections addressed to the VM's LAN IP, subject to firewall policy. A listener bound only to loopback is reachable from software inside the VM but not directly from another LAN device. Do not change binding behavior without understanding the server configuration and your intended client placement.

Join from the local network

On a computer with a compatible Minecraft Java client, add or directly connect to the VM's LAN address. Use port 25565 where the client asks for an explicit port. This LAN test confirms several things at once: PaperMC is running, the VM bridge works, the guest address is correct, and any local firewall permits the connection.

A successful local test is particularly important when the Localtonet client will run outside the VM. If that device cannot reach the VM locally, the relay cannot make the final hop either. Test from the intended Localtonet client device when possible, not only from an unrelated machine on a different network segment.

Routine operation, updates, backups, and configuration

A Minecraft server is a persistent workload, so installation is only the beginning. Plan how you will stop it cleanly, update PaperMC, protect world data, monitor storage growth, and recover from a failed change.

Console access and clean shutdowns

The documented administration path attaches to the named screen session as the minecraft user. Use the game server's administrative console for server-level operations. Avoid abruptly powering off the VM while the world is being written because forced interruption can leave data inconsistent.

The supplied evidence confirms the screen attachment command but does not establish every console command or keyboard sequence used by every release. For that reason, this guide does not invent a complete command catalog. Use the repository's maintained server-command documentation for the exact release you installed when performing administrative operations beyond basic verification.

PaperMC updates

The project includes an update.sh workflow that retrieves the latest stable PaperMC build through the Fill v3 API. The current implementation filters for the stable channel and validates the download using size and SHA-256 information. It also uses a project-specific User-Agent because the current API can reject or rate-limit requests that do not supply an appropriate one.

Do not manually reconstruct PaperMC download URLs from older API patterns. Current builds are obtained from URLs embedded in the Fill v3 response. A manually constructed legacy URL can return an error page or a nonexistent path.

The extracted project evidence confirms that the updater exists but does not provide a complete, version-independent operational sequence for invoking it, stopping and restarting the service, or rolling back. Before applying an update, consult the copy of the project documentation corresponding to your installed version, create a verified backup, and schedule enough time to test player connectivity afterward.

Backups

Back up world data, server configuration, plugin data, allowlists, permissions, and any other files required to reconstruct the server. A Proxmox VM backup or snapshot can help at the virtualization layer, but it should not be treated automatically as an application-consistent Minecraft backup. Coordinate backups with clean server state so files are not captured midway through a write.

The repository provides backup examples, but the available evidence does not establish one universal backup command, destination, retention schedule, or restore procedure. Those choices depend on your storage layout and operational requirements. At minimum, keep a copy outside the VM, monitor whether jobs actually complete, and periodically test restoration rather than assuming an archive is usable.

Resource monitoring

Watch memory pressure, CPU saturation, free disk space, and world growth. The automatic JVM calculation simplifies initial deployment, but it cannot predict plugin behavior or the workload generated by a particular player community. If performance degrades, distinguish between Java heap pressure, host CPU contention, storage latency, networking problems, and a specific plugin before changing several settings at once.

Provide remote Minecraft access with a Localtonet TCP tunnel

Once the Java server works locally, Localtonet can publish it through a TCP tunnel. Our client establishes an outbound connection to a selected relay server, so you do not need inbound router port forwarding, a public IP address, firewall changes at the internet edge, or a VPN for ordinary player connections.

The tunnel remains available only while the selected Localtonet device is connected and the tunnel is running. Creating a tunnel record is not enough. You must start it, and stopping the client, shutting down the VM, or stopping the tunnel removes public availability.

Choose the correct local target

Give invited players the Localtonet public endpoint, not the private VM address. Private addresses such as those in typical home or office ranges are not globally routable and should not be expected to work over the internet.

Security and exposure checklist

Removing router port forwarding reduces one configuration burden, but it does not make an internet-accessible Minecraft server risk-free. Anyone who knows or discovers a public game endpoint can attempt to connect. Treat the server as an exposed service and apply controls at the game, guest, virtualization, and account layers.

The project provides UFW guidance, but UFW must be installed before any ufw commands are used. Firewall policy depends on whether the Localtonet client is inside the VM or on another device. When both processes share the VM, the target may stay local. When they are separated, the guest firewall must allow TCP 25565 from the client device or relevant trusted subnet.

Do not open TCP 25565 broadly on the router merely because a local firewall example mentions that port. Localtonet's purpose in this workflow is to avoid inbound router forwarding. Also avoid disabling the guest firewall just to make a test pass. Identify the exact traffic path and add only the rule required by that design.

Troubleshooting the complete connection path

The installer cannot download PaperMC

Confirm that the VM has working DNS resolution, a valid system clock, outbound HTTPS connectivity, and enough free storage. If errors mention the retired PaperMC v2 API, an incorrect version object, or an HTTP 404 generated from an old URL pattern, make sure you are using the maintained v3.0-era scripts that use Fill v3.

Current scripts supply the required project User-Agent, select a real patch version from the newest version group, filter for stable builds, and consume the API-provided download URL. Repeatedly modifying a legacy URL is not a reliable fix.

Java reports an unsupported version

Check the active runtime:

java -version

Current PaperMC requires Java 21. If an older Java installation remains the system default, PaperMC can fail even when Java 21 is also installed. The project installer includes a fallback to Amazon Corretto 21 when OpenJDK 21 is absent from configured repositories, so review the installer output for repository or package failures.

No process is listening on TCP 25565

Attach to the documented screen session and inspect the server output. If there is no session, review the installation and service state. Confirm that the VM has sufficient memory and disk space and that integrity checks did not reject the downloaded server file. A stopped or failed PaperMC process leaves the tunnel with nothing to forward to.

LAN players cannot connect

Verify the address with ip -br address, confirm the listener with ss -ltn, and make sure the player is using the VM's bridged LAN address rather than loopback. Check Proxmox bridge selection, VLAN placement, guest firewall policy, and any firewall between network segments.

If the server listens only on loopback, a separate LAN device cannot reach it. Do not expose additional interfaces blindly. First determine whether the intended design is to place the Localtonet client in the same VM or permit a controlled LAN path from a separate client device.

The tunnel is created but the public endpoint does not work

Confirm that the tunnel was started. Then check that the selected Localtonet device is online, the device token belongs to that client, the selected relay is available, and the tunnel type is TCP. Verify the target address from the Localtonet client's own network context.

A frequent addressing mistake is using 127.0.0.1 when our client runs on another machine. On that other machine, loopback points back to the client machine itself, not to the Minecraft VM. Use the VM's reachable LAN address in that arrangement.

The Minecraft client times out remotely

Test the local path again from the device running our client. Confirm that PaperMC has not stopped and that the VM address did not change after a DHCP lease renewal or reboot. Then verify that the player entered both the current public host and the current public port exactly as shown in the dashboard.

If the local path succeeds but the public path fails, restart only the relevant component and observe its state rather than changing the VM, PaperMC configuration, firewall, and tunnel simultaneously. Controlled changes preserve evidence and make the fault easier to isolate.

The server works until the VM reboots

Determine whether the Minecraft service and Localtonet client are both configured to run after boot in your installation. The project includes a systemd service definition for Minecraft, but customized deployments may differ. Localtonet availability also depends on the selected client being connected and the tunnel running. Verify each lifecycle separately after a reboot.

Players experience poor performance

Separate game-server performance from network reachability. High server tick time, world-generation stalls, plugin overhead, CPU contention, memory pressure, and slow storage can affect all players, including those on the LAN. Tunnel or route latency is more likely when local play is healthy but remote play is consistently delayed.

Test with the same world and workload, watch VM resource use, and avoid making several JVM, plugin, network, and tunnel changes at once. No specific latency, throughput, or performance improvement is guaranteed because results depend on the host, guest allocation, network path, relay selection, player location, and Minecraft workload.

Frequently asked questions