Get started with VoidPort

Quick Start

Get your local server online in under 2 minutes.

1. 1

   Create an account

   Sign up at voidport.app/register and choose a plan.

2. 2

   Create a tunnel in the dashboard

   Go to Dashboard > Tunnels > Create tunnel. Pick what you're hosting and a region.

That's it. Your server is now reachable at the public address shown in the dashboard.

Guides for specific games, with the ports they need: Minecraft, Terraria and more.

Installation

On Windows the installer puts voidport.exe in %LOCALAPPDATA%\VoidPort and adds it to your PATH. On macOS and Linux it installs to /usr/local/bin, or ~/.local/bin without root or sudo.

Manual Download

Download binaries directly:

• Linux x64
• Linux ARM64
• Windows x64
• macOS Apple Silicon
• macOS Intel

Verify Installation

$ voidport --version

Creating a Tunnel

Via Dashboard

1. Log in to your dashboard
2. Click "Create tunnel"
3. Pick what you're hosting, or "Custom port" with TCP, UDP or both
4. Give it a name (e.g. "minecraft") and choose a region (Nuremberg, Helsinki, Ashburn or Hillsboro)
5. If the server runs on another machine, enter its target host
6. Click "Create tunnel", start the CLI, then click "Test connection"

After creating it, the dashboard shows your tunnel's token and the command to start it. You can find both again on the tunnel's page. Keep the token secret.

Starting it

Run this on the machine that hosts your server:

$ voidport connect <token>

Forward to a different local port just this once:

$ voidport connect <token> --port 25566

Run several tunnels in one window, for example game and voice chat:

$ voidport connect <token1> <token2>

Via the CLI

You can also create and run tunnels from the terminal. This needs a one-time voidport login.

$ voidport login

$ voidport tunnel --preset minecraft-java

voidport up starts all tunnels saved on this machine, voidport list shows them.

Other Machines & Docker

By default the CLI forwards to the computer it runs on. If your server runs somewhere else, set the tunnel's target host: in the create form, on the tunnel's page under Settings, or with voidport tunnel --host. The start command stays voidport connect <token>; the CLI picks up the target host by itself. --host on the command line overrides it.

The target host is a name or IP address as seen from the machine running the CLI, without http:// or a port:

A device on your network

A NAS, a second PC or a console server in your LAN:

192.168.1.20

nas.local

The machine running the CLI must reach it: test with ping 192.168.1.20 and check that the server allows connections from other machines (not only from 127.0.0.1).

Docker

If the CLI runs directly on the Docker host, publish the server's port (-p 25565:25565) and leave the target host empty.

If the CLI runs in a container of its own in the same Docker network as your server (for example as a service in your Compose file), use the server's container or service name as the target host (see Docker Container):

mc

Websites over HTTPS

Tunnels forward raw TCP/UDP. A website that uses HTTPS will show a certificate warning, because the browser connects to <relay>.voidport.net and the certificate is issued for another name. Plain HTTP and game servers are not affected. HTTPS on your own domain solves this.

Docker Container

The CLI also runs as a container next to your server, for example in the same Compose file. Nothing is published on the host: players connect through the relay. Create the tunnel in the dashboard, then pass its token and the server's service name:

services:
  mc:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
    volumes:
      - mc-data:/data

  voidport:
    image: ghcr.io/voidmind-io/voidport:latest
    environment:
      VOIDPORT_TOKEN: ${VOIDPORT_TOKEN}
      VOIDPORT_HOST: mc
    depends_on:
      - mc
    restart: unless-stopped

volumes:
  mc-data:

$ VOIDPORT_TOKEN=<token> docker compose up -d

$ docker compose logs voidport

The log shows the public address. VOIDPORT_TOKEN takes several tokens, separated by commas (e.g. game and voice chat). VOIDPORT_HOST is the service name of your server; VOIDPORT_PORT overrides the tunnel's local port (one token only). VOIDPORT_TOKEN_FILE reads the token(s) from a file instead, e.g. a Compose secret at /run/secrets/voidport_token. docker compose down disconnects the tunnel cleanly.

Minecraft Bedrock

With itzg/minecraft-bedrock-server, create the tunnel with the Bedrock template. The voidport log shows a server-udp-ports=… line: set its value as SERVER_UDP_PORTS on the mc service and restart it.

SERVER_UDP_PORTS: "<relay IP>:<public port>:19132"

Pterodactyl & Pelican

If your servers run in the Pterodactyl or Pelican panel, the tunnel runs as a server of its own on the same node, with the VoidPort Tunnel egg. Nothing needs to be port-forwarded on the node.

1. Create the tunnel in the dashboard and copy its token.
2. As panel admin, import the egg egg-voidport-tunnel.json: under Admin > Nests > Import Egg in Pterodactyl, under Admin > Eggs > Import in Pelican (also from the URL).
3. Create a server with the VoidPort Tunnel egg on the node of your game server. The panel requires an allocation: any free one works, the tunnel doesn't use it. 128 MB of memory is enough.
4. Set Tunnel Token and, as Target Port, the port of your game server's allocation, then start the server.

Target Host defaults to 172.18.0.1, the node as seen from containers on the default pterodactyl0 network. It reaches allocations bound to 0.0.0.0. If your game server's allocation is bound to a specific IP, enter that IP.

Tunnel Token is visible to everyone in the panel who can see this server's startup variables (admins and subusers with startup access), and the token alone runs the tunnel. Use a tunnel just for this server, and if panel access changes, generate a new token in the dashboard (Regenerate token) and enter it in the panel.

The console shows the public address and online, and the panel marks the server as running. Stopping the server disconnects the tunnel cleanly. Several tokens, separated by commas, run together (e.g. game and voice chat); leave Target Port empty then, each tunnel uses its saved local port.

Minecraft Without a Port

Minecraft Java looks up an SRV record before it connects, so players don't need to type the port. Give your tunnel a name and players join with survival.voidport.net instead of nbg1.voidport.net:30421.

Set the name on the tunnel's page under Address without port, in the create form when you pick Minecraft: Java Edition, or from the CLI:

$ voidport tunnel --preset minecraft-java --address survival

Names are 3-32 characters (a-z, 0-9, hyphens), first come, first served. A new name can take a few minutes to work everywhere. The name only works in Minecraft Java: it is not a website address.

Step by step: Minecraft server without port forwarding.

Bedrock Edition doesn't look up SRV records. Bedrock players still need the address with the port.

Your own domain

To use a domain you own, e.g. play.example.com, create an SRV record at your DNS provider. The tunnel's page shows the exact values and has a Check button. With the example values:

_minecraft._tcp.play.example.com. 300 IN SRV 0 5 30421 nbg1.voidport.net.

Name _minecraft._tcp.play (in the example.com zone), priority 0, weight 5, your tunnel's public port, target your tunnel's relay host. With Cloudflare, the record must be "DNS only". If the tunnel moves to another relay or port, update the record.

Real Player IPs (PROXY protocol)

Through a tunnel, your server sees every connection coming from the machine running the CLI. With PROXY protocol turned on, the relay puts the visitor's real IP and port in front of each TCP connection (PROXY protocol v2), so your server sees the real player addresses.

Only turn it on if your server is set up to expect it. A server that doesn't expect the header rejects every connection. TCP tunnels only.

Turn it on in the create form, on the tunnel's page under Settings, or with voidport tunnel --proxy-protocol for a new tunnel. A change applies when the CLI reconnects (restart it). Then enable it in your server:

Paper (config/paper-global.yml)

proxies:
  proxy-protocol: true

Velocity (velocity.toml, [advanced])

haproxy-protocol = true

BungeeCord / Waterfall (config.yml, under listeners)

proxy_protocol: true

nginx

listen 8080 proxy_protocol;

With Velocity or BungeeCord, enable it on the proxy only, not on the servers behind it. Vanilla and Spigot servers can't read the header: leave it off. In nginx the address is in $proxy_protocol_addr.

Minecraft Status Badge

Show your Minecraft: Java Edition server on a website, forum or GitHub README: a small image with online/offline and players, and a JSON status. No plugin and no extra software; VoidPort asks your server for its status through the tunnel.

1. Open your tunnel in the dashboard and go to Settings
2. Turn on Status badge
3. Copy the code for Markdown, HTML or BBCode

![Minecraft server status](https://api.voidport.app/badge/<id>.svg)

Formats

.svg is the image (status and players), .json the full status with version and message of the day, for your own scripts or website (CORS allowed).

JSON example

{
  "name": "survival",
  "online": true,
  "address": "hel1.voidport.net:21234",
  "players": { "online": 3, "max": 20 },
  "version": "Paper 1.21.1",
  "motd": "A Minecraft Server",
  "checked_at": "2026-09-28T12:00:00Z"
}

The status updates at most once a minute. Only Minecraft: Java Edition tunnels have a badge. The badge is off by default and its link is random, not your tunnel ID; turning it off hides it.

HTTPS on Your Own Domain

Serve a website or API as https://app.example.com on the standard port 443, with a domain you own. The relay reads only the hostname the browser asks for (SNI) and forwards the encrypted connection unchanged to your tunnel; it never sees the content. TLS ends either in the VoidPort CLI, with an automatic certificate, or on your own server (Caddy, nginx, Traefik, ...).

1. Under Domains in the dashboard, add the hostname and choose who handles the certificate: the VoidPort CLI (automatic) or your own server.
2. At your DNS provider, create the TXT record _voidport-challenge.app.example.com with the value shown and click Verify. Keep the TXT record in place as long as you use the domain with VoidPort.
3. Assign the hostname to a TCP tunnel, on the Domains page or on the tunnel's settings tab. With the CLI handling TLS, the tunnel's target is your plain-HTTP server (e.g. 3000); with your own server, its HTTPS port (e.g. 443).
4. Create a CNAME from app.example.com to the tunnel's relay (e.g. nbg1.voidport.net). For a root domain, where CNAME isn't allowed, use an A record with the relay's IP instead.

Behind Cloudflare, set the record to DNS only (grey cloud). The orange proxy terminates TLS itself and would never reach your server. Only domains you own can be used, never VoidPort's own.

Certificates

With the VoidPort CLI there is nothing to do: once the hostname is verified and points to the relay, the CLI gets a Let's Encrypt certificate and renews it (update to the latest CLI). With your own server: port 80 is not forwarded, so the HTTP-01 challenge doesn't work; use one of these:

• TLS-ALPN-01 (automatic, through the tunnel): Caddy does this by default once HTTP-01 is off. Traefik: a certificate resolver with tlsChallenge.
• DNS-01: works everywhere (certbot, acme.sh, Caddy/Traefik DNS plugins).

Caddy (Caddyfile)

{
  # port 80 is not reachable through the tunnel
  auto_https disable_redirects
}

app.example.com {
  tls {
    issuer acme {
      disable_http_challenge
    }
  }
  reverse_proxy localhost:3000
}

PROXY protocol works here too: with it turned on, the connection starts with the header before the TLS handshake (nginx: listen 443 ssl proxy_protocol;). Plain HTTP on port 80 and wildcard hostnames are not supported.

Offline Notifications

Get a message when a tunnel goes offline: its CLI or agent disconnects and doesn't come back within the grace period (2 minutes by default, 1 to 60). Optionally also when it comes back online. Set it up per tunnel on the tunnel's Settings tab under Notifications, then send a test.

Channels

• Email to your account address.
• Discord: in Discord, open the channel's settings, go to Integrations > Webhooks, create a webhook and paste its URL (https://discord.com/api/webhooks/...).
• Webhook: an HTTPS POST with a JSON body to your own URL, signed so you can check that it comes from VoidPort.

Repeated drops within a short time are combined: at most one notification per 10 minutes. Tunnels that are stopped because the subscription ended, the account is suspended or the monthly transfer is used up send nothing.

Webhook format

VoidPort sends a POST with Content-Type: application/json and these headers:

• X-VoidPort-Event: tunnel.offline, tunnel.online or test
• X-VoidPort-Timestamp: Unix time in seconds
• X-VoidPort-Signature: sha256= followed by the hex HMAC-SHA256 of timestamp + "." + raw body, keyed with your signing secret

{
  "event": "tunnel.offline",
  "tunnel": {
    "id": "3f0c...",
    "name": "survival",
    "address": "nbg1.voidport.net:25565"
  },
  "since": "2026-09-28T12:00:00Z",
  "sent_at": "2026-09-28T12:02:05Z"
}

since is the time the tunnel went offline or came back online.

The signing secret is shown once, when you save the first webhook URL. You can regenerate it on the same settings tab; the old secret stops working right away.

Verifying the signature (Node.js)

import crypto from 'node:crypto';

// rawBody: the request body exactly as received (string or Buffer)
function verifyVoidPort(headers, rawBody, secret) {
  const timestamp = headers['x-voidport-timestamp'];
  const signature = headers['x-voidport-signature'] ?? '';
  // Reject requests older than 5 minutes
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use the raw request body, before any JSON parsing. Rejecting old timestamps stops replayed requests.

Any 2xx response counts as delivered. Redirects are not followed and a request times out after 10 seconds. The URL must use HTTPS and point to a public address.

Access Control

Limit who can connect to a tunnel, on the tunnel's Settings tab under Access. The rules apply to the public port (TCP and UDP) and to HTTPS on your own domain.

IP allowlist

Up to 50 IPv4 or IPv6 addresses or CIDR ranges, e.g. 203.0.113.7 or 198.51.100.0/24; a single address needs no prefix. With an empty list everyone may connect, otherwise only the listed addresses. Add my IP adds the address you are browsing from.

Countries

Choose Only allow these countries or Block these countries. The country is determined from the visitor's IP address, which is not always exact, for example with VPNs or mobile networks.

Both rules apply together: a visitor must pass the allowlist and the country rule. Changes apply within seconds while the tunnel keeps running. Open connections that are no longer allowed are closed.

IP geolocation by DB-IP, licensed under CC BY 4.0.

Run as a Service

On a server, or a PC that should keep the tunnel up without anyone logged in, install the CLI as a system service. It starts with the machine and restarts by itself if it stops.

Linux and macOS

$ sudo voidport service install

Without names it runs all tunnels you created on this machine with voidport tunnel. Name them to pick some (sudo voidport service install mc), or use tokens from the dashboard: sudo voidport service install --token <token>.

Windows

Open PowerShell with Run as Administrator:

$ voidport service install --token <token>

Managing it

$ voidport service status

$ voidport service logs -f

$ sudo voidport service update

$ sudo voidport service uninstall

The service runs its own copy of the CLI in a folder only administrators can change. After voidport update, run service update (on Windows in an administrator shell) so the service uses the new version too.

The service keeps the tunnel tokens in a file only the service and administrators can read (/etc/voidport/service.json, on Windows %ProgramData%\VoidPort). It doesn't need your login. Run service install again to change the tunnels. On Linux the service uses systemd and runs as the system user voidport; the log is in the journal. On macOS it is a launchd daemon logging to /var/log/voidport.log.

CLI Commands

$ voidport connect <token> [<token> ...]

$ voidport login

$ voidport tunnel --preset minecraft-java

$ voidport up [<name> ...]

$ sudo voidport service install [<name> ...]

$ voidport list

$ voidport presets

$ voidport relays

$ voidport status [<name>]

$ voidport delete <name>

$ voidport update

TCP vs UDP

Not sure which to choose? Most applications use TCP. Minecraft Java uses TCP, Minecraft Bedrock (1.26.50 and later) uses both.

All presets with their ports: Games. Guides: Minecraft, Terraria.

Valheim: the server uses the game port and the Steam query port right after it (2456 and 2457). With voidport tunnel --preset valheim the query port is forwarded automatically, on the tunnel's public port + 1. Share only the tunnel address (relay:port, e.g. nbg1.voidport.net:30420); the query port (30421 in the example) needs no extra tunnel. Requires CLI 0.2.25 or newer.

Plans & Limits

Sticky ports: Your public port stays the same across reconnects, so players don't need a new address.

Troubleshooting