Endpoint discovery

For clients to establish WireGuard connections, they need to know your server’s public IP address and port. atreoLINK derives the public address from the agent’s authenticated connection and keeps the DDNS records current.

Discovery flow

The agent talks to atreoLINK over Ed25519-authenticated connections. atreoLINK terminates each connection directly, so it can see the agent’s public source address — both IPv4 and IPv6 are reported, each from a connection of the matching family.

On startup, and on every maintenance tick, the agent:

1. Sends a device:endpoint report to atreoLINK. The IP field is omitted in the normal case.
2. atreoLINK derives the public address from the observed source of each authenticated connection — an IPv4 source updates the A record, an IPv6 source updates the AAAA record.
3. atreoLINK writes the matching DDNS record for your per-device hostname. Each family is independent: if only one is reachable, only that record is updated — the other is left untouched.

DDNS updates

atreoLINK acts as a dynamic DNS service for your per-device hostname. When a mobile client wants to connect, atreoLINK resolves the current endpoint address.

This means:

• Your public IPv4 and IPv6 addresses can change (common with residential ISPs) and clients will still connect. Every periodic report re-derives the addresses from the live connections, with no STUN or third-party IP-echo dependency.
• The endpoint is refreshed on every startup and on every maintenance tick.
• No manual DNS configuration is needed.

When the IP is overridden

Normally you leave endpoint_ip / ENDPOINT_IP unset and atreoLINK uses the address it observes on the agent’s authenticated connection. You only set it if that auto-detected address is wrong (for example a CGNAT or proxied control path), in which case it takes precedence.

Configuration	Behaviour
endpoint_ip / endpoint_port unset (normal)	atreoLINK uses the observed source address of the authenticated connection.
endpoint_ip set	The report carries that IP and it wins over the observed address. For CGNAT / proxied control paths where the connection’s source IP isn’t the WireGuard-reachable one.

atreoLINK rejects a private, loopback, link-local, or RFC-6598 (CGNAT) address with a 422; the agent logs that response so a misconfigured override is visible.

Note

Remote access works whenever the WireGuard UDP port is reachable from the internet, whether that port was opened automatically (PCP/NAT-PMP/UPnP, or an IPv6 firewall pinhole) or by a manual port forward. When no inbound path is reachable at all (for example behind CGNAT), the agent advertises a relay endpoint instead so clients can still connect.

Maintenance loop

After initial setup, the agent runs a maintenance loop every 5 minutes:

1. Re-sends the device:endpoint report so atreoLINK re-derives the address from the live connection.
2. If UPnP/NAT-PMP is enabled, renews the port mapping and verifies the external port hasn’t changed.
3. When port mapping is unavailable, logs an actionable “forward UDP <port>” message every cycle.
4. Sends push notifications if a previously working port mapping is lost (after the 35-minute threshold).