docs: automatic UPnP port forwarding (clearnet + StartTunnel)

start-os/src/clearnet.md

@@ -60,11 +60,13 @@ StartOS tests DNS automatically when you add or enable a public domain, and will
 
 To expose a public domain to the Internet, the appropriate port must be forwarded in the corresponding gateway. StartOS tests port forwarding automatically when you add or enable a public domain, and will guide you through the setup if the test fails.
 
+When a public address is enabled, StartOS first **attempts to open the port automatically** on the corresponding gateway, using PCP (preferred), then NAT-PMP, then UPnP. If the gateway supports one of these (and it is enabled), no manual step is required — and when the address is later disabled or deleted, StartOS removes the port forward it created. This is best-effort: if the gateway supports none of them, the automatic test will fail and you create the rule manually as described below.
+
 > [!TIP]
 > Most websites and APIs on the Internet are hosted on port `443`. Port `443` is so common, in fact, that apps and browsers _infer_ its presence. The _absence_ of a port _means_ the port is `443`. With rare exceptions, domains on StartOS also use port `443`, and that is why your domains usually do not display a port. The port forwarding rule needed for these standard domains is always the same, which means you only have to do it once!
 
 How you create a port forwarding rule depends on the type of gateway.
 
-- **Routers**: Port forwarding is supported by all routers and easy to do. Refer to your router's manual for instructions.
+- **Routers**: Port forwarding is supported by all routers and easy to do. Many routers also support PCP, NAT-PMP, or UPnP, in which case StartOS opens the port for you automatically. If none is available or they are disabled, refer to your router's manual to add the rule manually.
 
-- **StartTunnel**: Refer to the [StartTunnel Port Forwarding guide](/start-tunnel/port-forwarding.html).
+- **StartTunnel**: StartTunnel supports PCP and UPnP over the tunnel, so StartOS opens the required port automatically. To add or manage forwards manually, refer to the [StartTunnel Port Forwarding guide](/start-tunnel/port-forwarding.html).

start-tunnel/src/architecture.md

@@ -14,7 +14,7 @@ StartTunnel is a virtual private router (VPR) — a minimal, self-hosted router
 
 - **Create Subnets** — Each subnet is a private LAN, just like the one your home router creates
 - **Add Devices** — Servers, phones, laptops join the LAN and get an IP address and WireGuard config
-- **Forward Ports** — Expose specific ports on specific devices to the public Internet, just like port forwarding on a home router
+- **Forward Ports** — Expose specific ports on specific devices to the public Internet, just like port forwarding on a home router. StartTunnel also acts as a port-control gateway (PCP and UPnP), so a StartOS device can open its own ports automatically
 
 ## How StartTunnel Compares
 

start-tunnel/src/port-forwarding.md

@@ -5,6 +5,11 @@ Port forwarding exposes a device's port on your VPS's public IP address. This is
 > [!WARNING]
 > Port forwarding requires a **dedicated public IPv4 address** on your VPS. Shared IPv4 addresses (CGNAT, shared NAT, load-balanced IPs) and IPv6-only VPSes cannot be used to expose services to the clearnet. Confirm with your VPS provider before purchasing.
 
+> [!NOTE]
+> StartTunnel acts as a port-control gateway for connected devices, speaking PCP (preferred) and UPnP. A StartOS server using this tunnel opens the ports it needs **automatically** when you enable a public address — the same way it would behind a home router — and removes them when the address is disabled or deleted. For security, an automatically created forward always targets the requesting device's own tunnel IP; a device can only open ports to itself. The steps below are for adding or managing forwards manually.
+
+## Add a forward manually
+
 1. In StartTunnel, navigate to `Port Forwards` and click "Add".
 
 1. Select the external IP address you want to use (there is usually only one).