start-tunnel CLI Reference

The start-tunnel CLI manages a StartTunnel server — a WireGuard-based gateway that provides clearnet access to devices behind NAT. Run it as root directly on the StartTunnel server, or use start-cli tunnel to manage it remotely from a StartOS server.

Global Options

-c, --config <PATH> — Configuration file path
-H, --host <URL> — StartOS server URL
-r, --registry <URL> — Registry URL
--registry-hostname <HOST> — Registry server hostname
-t, --tunnel <URL> — Tunnel server address
-p, --proxy <URL> — HTTP/SOCKS proxy
--id-key-path <PATH> — Identity signing key path (--developer-key-path is accepted as an alias)
--id-key-gpg <KEY> — Sign through gpg-agent with this GnuPG key (fingerprint, key ID, or user ID) instead of the identity key file

Shell Completion

The Debian package enables Bash tab completion automatically in new shells. start-tunnel completions <shell> prints a completion script for Bash, Zsh, fish, elvish, or PowerShell. For example, eval "$(start-tunnel completions zsh)" enables completion in Zsh.

Authentication

Manage passwords, enrolled device keys, and authorized SSH keys for remote access.

`start-tunnel auth logout <SESSION>`

Remove an enrolled device key.

`start-tunnel auth set-password`

Set the web UI password.

`start-tunnel auth reset-password`

Reset the web UI password.

`start-tunnel auth get-pubkey`

Retrieve the server’s public key.

`start-tunnel auth session list`

List enrolled device keys.

--format — Output format

`start-tunnel auth session kill [--pubkey <KEY>]...`

Remove enrolled device keys.

`start-tunnel auth key add <NAME> <KEY>`

Add an authorized SSH key.

`start-tunnel auth key list`

List authorized SSH keys.

--format — Output format

`start-tunnel auth key remove <KEY>`

Remove an authorized SSH key.

Subnets

Create and remove WireGuard subnets. Each subnet is an isolated network. The <SUBNET> argument is passed to the parent subnet command.

`start-tunnel subnet <SUBNET> add <NAME>`

Create a new subnet with the given name.

`start-tunnel subnet <SUBNET> remove`

Remove a subnet and all its devices.

`start-tunnel subnet <SUBNET> set-ipv6`

Set (or clear) the routed IPv6 prefix delegated to the subnet. Each host on the subnet is assigned a globally-routable /128 out of it. See IPv6.

--prefix <PREFIX> — The routed prefix (e.g. 2001:db8:abcd::/64). Omit to disable IPv6 on the subnet.

`start-tunnel subnet <SUBNET> set-wan`

Pin the IPv4 address used for the subnet’s egress SNAT and published-port keys. Use an address assigned to the StartTunnel host: a public IPv4 on a directly connected VPS, or its private local IPv4 behind upstream NAT. Individual devices can override it with device set-wan.

--wan-ip <IP> — The address to pin. Omit to go back to the server default.

For a host behind NAT, see Devices › Hosting behind NAT.

Devices

Manage devices within a subnet. Each device gets a unique WireGuard configuration.

`start-tunnel device add <SUBNET> <NAME> [IP]`

Add a device to a subnet. Optionally assign a specific IP address.

--kind <client|server> — Device kind (default client). A server enables gateway autoconfiguration (DNS injection + auto-publish) by default.

`start-tunnel device list <SUBNET>`

List all devices in a subnet.

--format — Output format

`start-tunnel device remove <SUBNET> <IP>`

Remove a device from a subnet.

`start-tunnel device set-wan <SUBNET> <IP>`

Pin the device’s IPv4 address for egress SNAT and published-port keys, overriding its subnet’s setting.

--wan-ip <IP> — An IPv4 address assigned to the StartTunnel host. Omit to inherit the subnet’s setting.

`start-tunnel device show-config <SUBNET> <IP>`

Display the WireGuard configuration file for a device.

--endpoint <HOST> — An IPv4 address, IPv6 address, or DNS name used only for the returned config’s WireGuard Endpoint. Supply the host without a scheme, port, or path; the configured WireGuard port is retained. This does not change the device’s WAN assignment, SNAT, or published ports.

Without --endpoint, a public device or subnet WAN override supplies the endpoint. With neither override, StartTunnel uses a suitable address from the request, then the configured webserver listen address, then a detected public address. A non-public WAN override requires an explicit --endpoint instead of generating a private endpoint. The UI config dialog supplies the browser URL’s host by default and lets you edit it.

start-tunnel device show-config 10.59.0.1/24 10.59.0.2 --endpoint 203.0.113.10
start-tunnel device show-config 10.59.0.1/24 10.59.0.2 --endpoint 2001:db8::10
start-tunnel device show-config 10.59.0.1/24 10.59.0.2 --endpoint vpn.example.com

Port Forwarding

Expose a device’s port on the server’s public IP.

`start-tunnel port-forward add <EXTERNAL_PORT> <TARGET>`

Add a port forwarding rule mapping a public external port to a private target. The external IP is fixed server-side to the target device’s WAN.

--label <LABEL> — Human-readable label
--sni <SNI> — Hostname to SNI-demux on a shared external port (TLS services only); repeatable. Omit for a plain port forward.
--count <COUNT> — Number of contiguous ports to forward as a range (a PCP PORT_SET range), counting up from both the external port and the target port. Defaults to 1. Not valid together with --sni.

`start-tunnel port-forward remove <SOURCE>`

Remove a port forwarding rule.

`start-tunnel port-forward set-enabled <SOURCE>`

Enable or disable a port forwarding rule.

--enabled — Enable the rule

`start-tunnel port-forward update-label <SOURCE> [LABEL]`

Change or clear the label on a port forwarding rule.

HTTP Redirects

StartTunnel runs an HTTP→HTTPS redirect on port 80 of every public IPv4 it holds, so a plain http:// request to an exposed service bounces to https://. These are on by default; each address can be turned off individually. A redirect and a port-80 forward are mutually exclusive and never both enabled — forwarding port 80 is rejected while the redirect is on, and enabling the redirect is rejected while port 80 is forwarded.

`start-tunnel http-redirect list`

Show the port-80 redirect status of every public IPv4: whether it is enabled, and whether a port forward already occupies port 80 (which blocks enabling the redirect).

--format — Output format

`start-tunnel http-redirect set-enabled <IP>`

Turn the port-80 HTTP→HTTPS redirect on or off for a public IPv4. Enabling is rejected if a port-80 forward exists on that IP — delete the forward first.

--enabled — Enable the redirect; omit the flag to turn it off

IPv6 Pinholes

Expose a device’s port over IPv6 by opening a firewall pinhole on the device’s own global address (GUA — see IPv6). Unlike an IPv4 forward there is no NAT; a differing internal port turns it into a port-only translation on the same GUA (e.g. an 80 → 443 redirect). The GUA must be an address the tunnel delegates to a client (its subnet needs an IPv6 prefix).

`start-tunnel pinhole add <GUA> <EXTERNAL_PORT>`

Open a pinhole for [GUA]:EXTERNAL_PORT.

--internal-port <PORT> — Destination port on the GUA. Omit for a pure pinhole (internal == external); set a different value for a port remap (e.g. 80 → 443).
--label <LABEL> — Human-readable label
--count <COUNT> — Number of contiguous ports to open as a range, counting up from both the external and internal ports. Defaults to 1.