Minecraft Server with Twingate (Linux)

Overview

Running a Minecraft server for friends or family usually means port forwarding through your router. That works, but it exposes port 25565 to the entire internet. Automated scanners find open Minecraft ports within minutes, and your home IP address is visible to everyone who connects.

This guide takes a different approach. You install the Minecraft server directly on Linux using Java and systemd, and deploy a Twingate Connector using the native installation script. The Connector creates an outbound-only encrypted tunnel to Twingate’s network, and players install the Twingate Client to connect using the server’s private IP address, as if they were on your local network. The port never touches the public internet.

Architecture

[Player's Device]
     ↓ Twingate Client
[Twingate Cloud]
     ↓
[Twingate Connector]
     ↓
[Minecraft Server — port 25565]

The Twingate Connector on your server opens an outbound connection to Twingate Cloud. When players connect, their traffic routes through this encrypted tunnel. Your router doesn’t need any inbound ports or forwarding rules.

Prerequisites

• A Linux machine (physical or virtual) with at least 2 GB of RAM, 2 CPU cores, and 10 GB of free disk space. Ubuntu 22.04, Ubuntu 24.04, and Debian 12 are tested.
• Java 21 (OpenJDK) installed. Installation covered in Step 2.
• A Twingate account with access to the Admin Console. Sign up for free if you do not have one.
• SSH or terminal access to the Linux machine with sudo privileges.

Step 1: Create a Remote Network and Generate Connector Tokens

• Sign in to the Twingate Admin Console.
• Navigate to Remote Networks.
• Click Add Remote Network. Select a location (e.g., On Premise for a home server). Give it a descriptive name (e.g., “Home Lab” or “Minecraft Network”). Click Add Remote Network.
• From your new Remote Network, click on the undeployed Connector (or click Add Connector to create one).
• Select Linux as the deployment method.
• Click Generate Tokens.
• Authenticate when prompted.
• Copy the Access Token and Refresh Token. You will use these in the next step.

Step 2: Install and Configure the Server

Create a System User and Directory

• SSH into the Linux machine.
• Create a dedicated system user and installation directory:

sudo useradd -r -m -U -d /opt/minecraft -s /bin/bash minecraft
sudo mkdir -p /opt/minecraft/server
sudo chown -R minecraft:minecraft /opt/minecraft

Install Java

• Update the package list and install OpenJDK 21:

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

• Verify the Java installation:

java -version

You should see output indicating Java 21 is installed.

Download the Minecraft Server

• Switch to the minecraft user and navigate to the server directory:

sudo -u minecraft -s
cd /opt/minecraft/server

• Download the Minecraft server JAR. The download URL changes with each release. Visit minecraft.net/en-us/download/server to find the current link. Replace the URL below with the current version:

wget https://piston-data.mojang.com/v1/objects/[VERSION_HASH]/server.jar

Accept the EULA

• Create the EULA file:

echo "eula=true" > eula.txt

Configure Server Properties

• Create a basic server.properties file:

cat > server.properties << 'EOF'
server-port=25565
max-players=10
difficulty=normal
gamemode=survival
motd=Private Minecraft Server
view-distance=10
white-list=false
pvp=true
EOF

Create the systemd Service

• Exit the minecraft user shell and create the systemd service file:

exit
sudo nano /etc/systemd/system/minecraft.service

• Paste the following configuration:

[Unit]
Description=Minecraft Server
After=network.target

[Service]
Type=simple
User=minecraft
WorkingDirectory=/opt/minecraft/server
ExecStart=/usr/bin/java -Xmx2G -Xms1G -jar server.jar nogui
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

• Save and close the file (Ctrl+O, Enter, Ctrl+X in nano).

Start the Minecraft Server

• Reload systemd, enable the service to start on boot, and start it now:

sudo systemctl daemon-reload
sudo systemctl enable --now minecraft

• Verify the server is running and watch the startup process:

sudo journalctl -u minecraft -f

Wait until you see a log line containing For help, type "help" (the full line reads Done (1.5s)! For help, type "help"). This indicates the world has finished generating. Press Ctrl+C to exit the log view.

Install the Twingate Connector

• Install the Twingate Connector using the one-line installer. Replace the placeholder values with your actual tokens and network name from Step 1:

curl "https://binaries.twingate.com/connector/setup.sh" | \
  sudo TWINGATE_ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>" \
  TWINGATE_REFRESH_TOKEN="<YOUR_REFRESH_TOKEN>" \
  TWINGATE_NETWORK="<YOUR_TWINGATE_NETWORK>" \
  bash

• Verify the Connector service is running:

sudo systemctl status twingate-connector

The status should show active (running).

Verify the Connector

• Return to the Twingate Admin Console.
• Navigate to Remote Networks and select your network.
• Click on the Connector. Verify that the Controller and Relay statuses both show Connected.

Step 3: Add the Minecraft Server as a Resource

Find Your Server’s Private IP Address

• On the Linux machine, run:

hostname -I | awk '{print $1}'

Note the IP address (e.g., 192.168.1.50).

Create the Resource

• In the Twingate Admin Console, navigate to Resources and click Add Resource.
• Select the Remote Network you created in Step 1.
• Configure the Resource:
  • Name: Minecraft Server
  • Address: Your server’s private IP address (e.g., 192.168.1.50)
  • Protocols: TCP port 25565
• Click Create Resource.

Assign Access

• After creating the Resource, Twingate prompts you to select which Groups can access it.
• Select the Group that contains your players (the default Everyone Group works for getting started) and click Grant Access.

Step 4: Connect Players

This section covers what each player needs to do on their own device.

Install the Twingate Client

Each player installs the Twingate Client on the device they play Minecraft from:

• Windows / macOS: twingate.com/download
• Linux: Linux Client install guide
• iOS: App Store, search “Twingate”
• Android: Play Store, search “Twingate”
• ChromeOS: Play Store, search “Twingate”

Sign In and Connect

• Open the Twingate Client.
• Enter your Twingate Network address (e.g., yournetwork.twingate.com).
• Sign in with the account the server admin invited you with.
• The Client connects and the Minecraft Server Resource appears in the Resource list.

Add the Server in Minecraft

• Open Minecraft Java Edition.
• Click Multiplayer, then Add Server.
• Enter the server’s private IP address as the Server Address (e.g., 192.168.1.50).
• Click Done, then select the server and click Join Server.

Step 5: Manage Player Access

Instead of managing Minecraft allowlists or editing banned-players.json, you can use Twingate Groups to control who can connect.

Invite Players to Twingate

• In the Admin Console, navigate to Team and click Add User.
• Enter the player’s email address. Repeat for each player.
• Each player receives an email invitation to create their Twingate account.

Create a Minecraft Players Group

• Navigate to Groups and click Add Group.
• Name it Minecraft Players.
• Add the users who should have access to the server.

Assign the Group to the Resource

• Navigate to Resources and select Minecraft Server.
• Under Access, remove the Everyone Group (if assigned) and add the Minecraft Players Group.
• Only users in the Minecraft Players Group can now reach the server.

Customizing the Server

Common Configuration Options

Adjust the Minecraft server by editing /opt/minecraft/server/server.properties:

After making changes, restart the server:

sudo systemctl restart minecraft

Troubleshooting

Players Cannot Connect to the Server

• Is the Twingate Client showing Connected on the player’s device?
• Does the Minecraft Server Resource appear in the player’s Twingate Client Resource list? If not, check that the player’s user account is in the correct Group.
• Is the server running? sudo systemctl status minecraft should show active (running).
• Does the private IP address entered in Minecraft match the server’s actual IP address?
• Is the player using Minecraft Java Edition? Bedrock Edition uses a different protocol and port.

Server Starts but Crashes

• Check the server logs: sudo journalctl -u minecraft -n 100
• The most common cause is insufficient memory. Edit /etc/systemd/system/minecraft.service and increase -Xmx2G to -Xmx4G, then run sudo systemctl daemon-reload && sudo systemctl restart minecraft.
• If using mods (Forge/Fabric), verify mod compatibility with the server version.

Connector Shows Offline in Admin Console

• Verify the TWINGATE_ACCESS_TOKEN, TWINGATE_REFRESH_TOKEN, and TWINGATE_NETWORK values were correct during installation.
• Check that the host machine has outbound internet access (the Connector needs to reach Twingate Cloud).
• Check Connector logs: sudo journalctl -u twingate-connector -n 50

Permission Denied Errors

• Verify the minecraft user owns all files: sudo chown -R minecraft:minecraft /opt/minecraft
• Verify the systemd service is running as the minecraft user: sudo systemctl status minecraft

Port Already in Use

• Another process is already listening on port 25565. Find it with: sudo ss -tlnp | grep 25565
• Stop the conflicting service or change the Minecraft server’s port in server.properties (and update the Twingate Resource to match).

Service Fails to Start

• Check for Java installation: java -version should return Java 21.
• Check logs for the specific error: sudo journalctl -u minecraft -n 100
• Verify the server.jar file exists in /opt/minecraft/server/ and is readable by the minecraft user.

World Data Lost

• World data is stored in /opt/minecraft/server/. If this directory is deleted, data is lost.
• Back up the entire /opt/minecraft/server/ directory periodically.

Next Steps

• Resources: Learn more about configuring Twingate Resources, including wildcard DNS and CIDR-based Resources.
• Security Policies: Add multi-factor authentication or device trust requirements for players connecting to your server.
• Deploy a Second Connector: Add a second Connector for high availability.
• Protect Your Home Lab: Extend Twingate to secure other services running on your home network.
• Docker version of this guide: If you prefer Docker Compose over native installation.