Devices

Every device on a StartTunnel subnet gets its own WireGuard configuration. Devices come in two kinds, listed in separate tables on the Devices page:

• Servers — a StartOS server that may configure the gateway on its own behalf: injecting DNS records for its private domains and auto-publishing ports (via PCP/UPnP). Both capabilities are on by default for a Server.
• Clients — a plain peer such as a phone or laptop that uses the tunnel for connectivity only, with no gateway-configuration abilities.

Adding a Device

1. In StartTunnel, navigate to Devices and click Add — on the Servers table for a StartOS box, or on the Clients table for a phone or laptop. Which button you click sets the device’s kind (there is no kind selector in the form).

2. Fill out the form:

   • Give the device a name (e.g. “Start9 Server”, “Phone”, “Laptop”).
   • Select a subnet (the default is fine).
   • Accept or choose an IP address on the subnet (the default is fine).
   • Optionally set the outbound IP — the WAN address the device’s traffic leaves from.
   • For a Server, Allow DNS injection and Allow auto-publish are enabled by default; uncheck either to withhold that capability. A Client has neither.
   • Click “Save”.

3. Download the resulting start-tunnel.conf (or copy to your clipboard).

4. Import the config into the appropriate app on the device:

   • StartOS server: Navigate to System > Gateways, click “Add”, name the gateway (e.g. “StartTunnel”), upload or paste the config, and click “Save”. The config’s # inbound: yes marker lets StartOS identify it as an inbound/outbound gateway, and each service interface automatically acquires new addresses corresponding to it.
   • Phone or tablet: Scan the QR code shown in StartTunnel using the WireGuard app.
   • Laptop or desktop: Download the config and import it into the WireGuard app.

Note

The WireGuard endpoint in the config dialog defaults to the host in your browser’s URL, independently of the outbound IP. Edit it to an IPv4 address, IPv6 address, or DNS name reachable from the device, then click Generate config. The file, clipboard copy, and QR code use the same generated config. An HTTPS reverse proxy may not forward WireGuard UDP: choose the tunnel host’s reachable address in that case. The configured WireGuard port is retained; the browser’s HTTP port is not used. The endpoint affects only the generated config, not WAN assignments or forwarding. For CLI use, supply device show-config --endpoint <HOST>; see Hosting behind NAT.

Server capabilities

A Server has two independently-toggleable capabilities, shown as switches in the Servers table:

• DNS injection — lets the server manage the DNS records StartTunnel serves for your private domains (see DNS Records).
• Auto-publish — lets the server publish its own ports via PCP/UPnP (see Published Ports).

Only enable these for servers you trust. Clients have neither capability.

Changing a device’s role

Use a device’s actions menu to Change to Server or Change to Client. Changing to Server turns both Server capabilities on; changing to Client turns them off and moves the device to the Clients table.

Outbound IP

By default a device’s outbound traffic leaves from its subnet’s outbound IP. On a VPS with more than one public IPv4 address, you can override this per device with the WAN IP field in the device’s Add/Edit dialog — choose Subnet default to inherit the subnet’s setting (the address it resolves to is shown in parentheses), or a specific address to pin this device’s egress. On a single-IP VPS there is only one choice, so leave it on Subnet default. To add another public IPv4 address to your VPS, see IPv4.

Hosting behind NAT

If the StartTunnel host has a private local address behind an upstream NAT, configure its WAN assignment separately from the public WireGuard endpoint. For example, with host address 192.168.1.10, upstream public address 203.0.113.10, subnet 10.59.0.1/24, and peer 10.59.0.2, run on the StartTunnel host:

start-tunnel subnet 10.59.0.1/24 set-wan --wan-ip 192.168.1.10
start-tunnel device show-config 10.59.0.1/24 10.59.0.2 --endpoint 203.0.113.10

To assign only this peer instead of the whole subnet, use start-tunnel device set-wan 10.59.0.1/24 10.59.0.2 --wan-ip 192.168.1.10. The WAN assignment controls both outbound SNAT and the local address used for published-port keys. Set it to the host’s assigned local address, not the public address held by the upstream router. The endpoint override is supplied each time you generate a config and leaves that WAN assignment unchanged. You can also use the UI config dialog, which starts with the browser URL’s host and lets you edit it before downloading or scanning the config.

On the upstream router, forward the configured WireGuard UDP port to 192.168.1.10 on the same port. The generated config retains that WireGuard port. For a service on peer port 443, create a manual forward:

start-tunnel port-forward add 443 10.59.0.2:443

This forward’s key is 192.168.1.10:443; use that local address when managing it, for example start-tunnel port-forward remove 192.168.1.10:443. Forward the corresponding service ports on the upstream router to 192.168.1.10 as well (StartTunnel’s plain IPv4 forwards cover both TCP and UDP). Public clients connect to 203.0.113.10.

The operator owns the upstream NAT and firewall rules. PCP/UPnP auto-publishing on StartTunnel does not configure the upstream router; use manual forwards for this workflow. A shared or carrier-grade NAT requires control of upstream port mappings or a dedicated public address.

IPv6

If a device’s subnet carries an IPv6 prefix, the device gets its own stable, globally-routable IPv6 address, shown in the IPv6 column of the Servers and Clients tables. The address is computed from the prefix and the device’s tunnel IP, so it never changes. It is the address to use when opening a pinhole from the CLI or adding a manual AAAA record on the DNS Records page.

Removing a Device

1. Navigate to Devices, select the device, and click “Remove”.