# Networking for normal humans

You run panel at home, your friends want to join your server, and you
have a consumer router. This page is for you.

## The 60-second version

1. panel gives every instance its **host ports** at create time (see
   [what the panel auto-allocates](#what-the-panel-auto-allocates)).
   The dashboard's instance card / Ports panel shows the exact numbers.
2. Log in to your router and **forward those ports** (right protocol —
   most games are UDP) to the LAN IP of the **agent box** running that
   instance.
3. Give your friends `your-public-ip:game-port`.

You do **not** need to forward the panel's own ports (8080/8443) for
people to *play* — only to administer the panel from outside.

## What the panel auto-allocates

At instance create time the controller assigns each declared port a
**host port** from the agent's configured port window — default
**7000–9999** (`controller/cmd/controller/portalloc.go`). You can set a
per-agent window in the agent edit modal (e.g. box A gets 7000–7999,
box B gets 8000–8999). The allocator:

- reserves ports of **stopped** instances too (they come back),
- probes live sockets so it won't hand out a port some other process holds,
- honors manual overrides from the Ports UI when they fit the window,
- errors when the window is exhausted (widen it or delete instances).

So the *actual* host port is usually **not** the game's default port —
always read it off the dashboard. Ports marked `internal` in the module
manifest (RCON, admin APIs) are **never** exposed on the host and never
need forwarding.

## Per-game port table

Defaults from each `modules/<id>/module.yaml` (`ports:`). "Forward"
means players/queries need it; internal ports are panel-only.

| Game | Port (default) | Proto | Forward? | Notes |
|---|---|---|---|---|
| 7 Days to Die | 26900, 26901, 26902 | udp | yes (all 3, contiguous) | 8080/tcp web dashboard optional; telnet 8081 internal |
| ARK: Survival Ascended | 7777, 7778 game + 27015 query | udp | yes | RCON 27020/tcp internal |
| Barotrauma | 27015 game + 27016 query | udp | yes | |
| Conan Exiles | 7777 game + 7778 pinger + 27015 query | udp | yes | RCON 25575/tcp internal |
| Core Keeper | 27015 | udp | yes | |
| DayZ | 2302 game/query | udp | yes | 2303/2304 optional; BE RCON 2305 internal |
| Dragonwilds | 7777 | udp | yes | |
| Empyrion | 30000–30003 (game, query, client, EAC) | udp | yes (all 4) | CSW 30004 internal; EAH API 30007/tcp only if you use EAH |
| Enshrouded | 15637 | udp | yes | |
| Factorio | 34197 | udp | yes | RCON 27015/tcp internal |
| Minecraft Bedrock | 19132 (+19133 IPv6) | udp | yes | |
| Minecraft Java | 25565 | tcp | yes | RCON 25575 internal |
| Palworld | 8211 game + 27015 query | udp | yes | RCON 25575/tcp internal |
| Project Zomboid | 16261, 16262 | udp | yes (both) | RCON 27015/tcp internal |
| Rust | 28015 | udp | yes | RCON 28016 internal; Rust+ 28082/tcp optional |
| Satisfactory | 7777/udp game + 8888/tcp reliable | both | yes (both) | |
| Sons of the Forest | 8766 game + 27016 query | udp | yes | |
| Soulmask | 8777 game + 27015 query | udp | yes | admin 8888/tcp internal |
| Terraria | 7777 | tcp | yes | |
| V Rising | 9876 game + 9877 query | udp | yes | |
| Valheim | 2456, 2457, 2458 | udp | yes (all 3, contiguous) | |
| Vein | 7777 game + 27015 query | udp | yes | RCON 7878/udp internal |
| Windrose | 7777 | udp | yes | |

Remember: these are the *container defaults* — forward the **host ports
the panel actually assigned** (dashboard → instance → Ports).

## Forwarding ports on a generic router

Every router is different; the shape is always:

1. Browse to your router's admin page — usually `http://192.168.1.1` or
   `http://192.168.0.1` (it's the "Default Gateway" in
   `ipconfig` / `ip route`).
2. Find **Port Forwarding** — sometimes under "NAT", "Virtual Server",
   "Gaming", or "Advanced".
3. Add a rule per port (or range): external port = internal port =
   the host port panel assigned; protocol per the table above; internal
   IP = the LAN address of the **agent** box.
4. Give the agent box a **static LAN IP** (DHCP reservation) so the rule
   doesn't break after a reboot.
5. Test from *outside* your network (phone on cellular). Sites like
   canyouseeme.org only test TCP — most game ports are UDP, so the real
   test is a friend joining.

If you're behind **CGNAT** (ISP gives you a shared public IP — common on
cellular/fiber ISPs), port forwarding can't work; use a VPN/tunnel
(WireGuard on a cheap VPS, playit.gg, Tailscale Funnel, etc.) or ask
your ISP for a public IP.

## What about `opnfwd`?

You may notice an "OPNsense auto-forward" card in the admin settings and
`opnfwd_*` code in the tree. That is **maintainer-specific automation**
for a home lab running an OPNsense firewall: when enabled, the panel
calls the OPNsense API to create port forwards automatically on instance
create/delete.

It is **off by default** (`panel_settings.opnfwd_enabled` must be
explicitly set to `true`) and is irrelevant to normal users — if you
don't run OPNsense, ignore it entirely and forward ports on your router
as described above.
