Manual port forwarding

atreoAGENT can open the WireGuard UDP port automatically via PCP, NAT-PMP, or UPnP. If your router doesn’t support any of these, or you’ve switched them off, you’ll need to forward the port yourself, which is fully supported.

atreoLINK works out your public IP from the agent’s authenticated connection and keeps the DDNS record current (see Endpoint discovery), so all you provide here is a reachable UDP port. You’d only set endpoint_ip if that auto-detected address turns out to be wrong (see CGNAT and proxied control paths below).

How you’ll know

The agent logs make this obvious:

Startup / every maintenance cycle when no port mapping is in place: port mapping unavailable: forward UDP 51820 to this host.
Members see “Connecting…” that hangs and never completes the handshake.

Steps

Pick a UDP port. The agent defaults to 51820. Pick anything 1024 or higher if that’s already in use, and set WG_PORT to match.
Forward the port in your router admin UI. The exact menu varies by router, but you’re looking for “Port forwarding” or “Virtual server”. Set:
```
Service       atreoAGENT WireGuard
Protocol      UDP
External port 51820
Internal IP   192.168.1.10   (your server's LAN IP)
Internal port 51820
```
(Optional) Stop the agent attempting auto port-mapping. If your router has no UPnP/NAT-PMP, or you’d rather it not try, disable it in docker-compose.yml:
```
services:
  atreoagent:
    environment:
      - WG_UPNP_ENABLED=false
```
Or in config.yaml:
```
wireguard:
  upnp_enabled: false
```

Restart:

docker compose restart atreoagent

Watch the logs:

endpoint reported to atreoLINK
tunnel connected

Members pick up the working endpoint within seconds of the next reconnect.

IPv6 reachability

IPv6 has no NAT, so there’s no port to forward. The agent instead opens an inbound firewall pinhole for the WireGuard UDP port on the gateway (via PCP or UPnP IGDv2). If your gateway supports neither, add the inbound rule yourself — allow UDP 51820 (or your WG_PORT) to the server’s IPv6 address — so the published AAAA endpoint is reachable. Set ipv6_pinhole_enabled: false / WG_IPV6_PINHOLE_ENABLED=false if you’d rather the agent didn’t attempt this.

Dynamic public IPs

Nothing to do. If your home IP changes (most consumer ISPs without a static-IP option), atreoLINK re-derives it from the agent’s authenticated connection on every periodic report and updates the DDNS record automatically, with no STUN, no third-party IP-echo, and no manual override to keep in sync. The manual port forward stays valid because it’s keyed on the LAN IP, not the public one.

CGNAT and proxied control paths

If your ISP runs CGNAT (common with mobile data and some ISPs), no port forward will reach you. Symptoms: your public IP starts with 100.64.x.x, 10.x.x.x, or 192.0.0.x, or whatismyip.com shows a different address than your router’s WAN status page.

The agent detects this and falls back automatically to the atreoLINK CGNAT relay — there’s nothing to configure, your server stays reachable off-LAN, and the tunnel stays end-to-end encrypted. A direct path performs better, so if you can arrange one it still wins:

Ask your ISP for a real public IPv4 (often free, sometimes a few pounds a month).
Switch to an IPv6 endpoint if your router and atreoLINK clients support it.

Either of those, once reachable, takes over from the relay; otherwise the relay carries you. See CGNAT relay for how it works and how to confirm it’s active.

Recovery

When connectivity comes back (you fixed the router, the ISP changed your IP back, etc.), existing tunnels reconnect automatically; no manual reconnect needed. If a previously working UPnP/NAT-PMP mapping was lost and later restored, the agent sends a Port mapping recovered notification to every paired phone.