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/SUMMARY.md

@@ -15,6 +15,7 @@
 - [Subnets](subnets.md)
 - [Devices](devices.md)
 - [Port Forwarding](port-forwarding.md)
+- [DNS Records](dns-records.md)
 - [Updating](updating.md)
 - [Uninstalling](uninstalling.md)
 

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/devices.md

@@ -19,6 +19,10 @@ Every device on a StartTunnel subnet — whether it's a server, phone, or laptop
    - **Phone or tablet**: Scan the QR code shown in StartTunnel using the [WireGuard app](https://www.wireguard.com/install/).
    - **Laptop or desktop**: Download the config and import it into the [WireGuard app](https://www.wireguard.com/install/).
 
+## Allowing DNS injection
+
+Each device has an **Allow DNS injection** setting (off by default). Enabling it lets that device manage the DNS records StartTunnel serves for your private domains — see [DNS Records](/start-tunnel/dns-records.html). Only enable it for devices you trust, such as your own StartOS server.
+
 ## Removing a Device
 
 1. Navigate to `Devices`, select the device, and click "Remove".

start-tunnel/src/dns-records.md

@@ -0,0 +1,29 @@
+# DNS Records
+
+StartTunnel can serve DNS records for your private domains, so names resolve to the right device for everyone connected to the tunnel. Records can be added by hand, or injected automatically over [RFC 2136](https://www.rfc-editor.org/rfc/rfc2136) by devices you have explicitly trusted.
+
+> [!NOTE]
+> A StartOS server using this tunnel injects the records for its private domains **automatically**, once you allow DNS injection for its device (see below). You normally won't need to add records by hand.
+
+## Allowing a device to inject records
+
+DNS injection is **off by default** for every device. Only enable it for devices you control and trust.
+
+> [!WARNING]
+> A device allowed to inject DNS records can create, overwrite, or delete any record StartTunnel serves. Enable this only for trusted devices, such as your own StartOS server.
+
+1. In StartTunnel, navigate to `Devices` and select the device.
+
+1. Enable **Allow DNS injection**, then save.
+
+The device may now add, update, and remove records via RFC 2136 DNS UPDATE. StartTunnel authorizes each request by the device's tunnel IP, so only that device's allowance is in effect.
+
+## Viewing and managing records
+
+1. In StartTunnel, navigate to `DNS Records`.
+
+1. The table lists every record StartTunnel serves — its name, type, value, and, for injected records, the device that added it.
+
+1. To add a record manually, click "Add", enter the name, type (A, AAAA, CNAME, or TXT), value, and TTL, and click "Save".
+
+1. To remove a record, select it and click "Remove".

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).