StartTunnel Documentation

StartTunnel is a virtual private router (VPR) — a minimal, self-hosted router that runs on a VPS instead of sitting in your house. Use it for private remote access to self-hosted services, or to expose services to the public Internet without revealing your home IP address.

Getting Started

• Installing

User Manual

• Subnets
• Devices
• Port Forwarding
• Updating
• Uninstalling

Reference

• start-tunnel CLI
• Architecture
• FAQ

Installing

Install StartTunnel on a Debian VPS by renting a server, running the one-line installer script, and initializing the web interface. The entire process takes just a few minutes.

Get a VPS

Rent a cheap Debian 12+ VPS with a dedicated public IP. Minimum CPU/RAM/disk is fine. For bandwidth, no need to exceed your home Internet’s upload speed.

Requirements

• Debian 13
• Root access
• Public IP (required for clearnet port forwarding; not required for private VPN use)

Important

StartTunnel is designed to be the sole application on your VPS. The installer disables UFW and manages its own firewall rules via iptables. Do not run other Internet-facing services on the same VPS.

Run the installer

SSH into your VPS and run:

curl -sSL https://start9labs.github.io/start-tunnel/install.sh | sh

Note

If DNS resolution is not working on your VPS, the installer will configure public DNS resolvers (Google, Cloudflare, Quad9) and back up your existing /etc/resolv.conf.

Initialize the web interface

StartTunnel can be fully managed from the command line, but it also offers a web UI for convenience. To set it up, run:

start-tunnel web init

This initializes a web server, creates a random password, generates a Root Certificate Authority (Root CA), and prints them all the console on completion.

Save the URL and password to your password manager, then follow instructions to trust the Root CA.

Note

The URL, password, and Root CA are only for accessing your StartTunnel’s web user interface. None are needed to use StartTunnel from the command line.

Trust your Root CA

You can access your StartTunnel web UI without trusting its Root CA by powering through the browser warning, but this is less secure and not recommended.

To trust your Root CA, select your operating system and follow instructions:

Next steps

• Subnets — Create isolated VLANs
• Devices — Add servers, phones, and laptops
• Port Forwarding — Expose ports on your VPS’s public IP

Subnets

A subnet is an isolated /24 VLAN (up to 254 devices). All devices on the same subnet can communicate with each other.

StartTunnel comes with a default subnet, which is sufficient for most users. You can create additional subnets to isolate groups of devices from each other.

Creating a Subnet

1. In StartTunnel, navigate to Subnets and click “Add”.
2. Name the subnet and accept or customize the IP range.
3. Click “Save”.

Removing a Subnet

1. Navigate to Subnets, select the subnet, and click “Remove”.

Warning

Removing a subnet disconnects all devices on it. Their WireGuard configs will no longer work.

Devices

Every device on a StartTunnel subnet — whether it’s a server, phone, or laptop — is added the same way. Each device gets a unique WireGuard configuration file.

Adding a Device

1. In StartTunnel, navigate to Devices and click “Add”.

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).
   • 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”. StartOS will now see the VPS as a gateway, and each service interface will automatically acquire 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.

Removing a Device

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

Port Forwarding

Port forwarding exposes a device’s port on your VPS’s public IP address. This is how you make services reachable from the public Internet.

1. In StartTunnel, navigate to Port Forwards and click “Add”.

2. Select the external IP address you want to use (there is usually only one).

3. Enter the external port and the internal (device) port as. In almost all cases, they will be the same.

4. If you are forwarding port 443 -> 443, you will see a checkbox to also forward port 80 -> 443. This is highly recommended, as it will automatically redirect HTTP to HTTPS.

5. Click “Save”.

Updating

Keep StartTunnel up to date using the web UI, CLI, or install script.

Web UI

Navigate to Settings > Version > Check for Updates.

CLI

Check for updates:

start-tunnel update check

Install the latest version:

start-tunnel update apply

Install script

Re-run the install command:

curl -sSL https://start9labs.github.io/start-tunnel/install.sh | sh

The installer detects the existing installation, prompts for confirmation, and restarts the service.

Uninstalling

StartTunnel is designed to run on a dedicated VPS. To remove it, simply destroy the VPS through your hosting provider. All WireGuard keys and configuration are stored on the VPS and will be removed with it.

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 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
• --cookie-path <PATH> — Cookie file path
• --developer-key-path <PATH> — Developer signing key path

Authentication

Manage passwords, sessions, and authorized SSH keys for remote access.

start-tunnel auth login

Log in and create an authenticated session.

start-tunnel auth logout <SESSION>

End an authentication session.

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 active sessions.

• --format — Output format

start-tunnel auth session kill [IDS...]

Terminate sessions.

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.

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.

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 show-config <SUBNET> <IP> [WAN_ADDR]

Display the WireGuard configuration file for a device. Optionally override the WAN address in the generated config.

Port Forwarding

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

start-tunnel port-forward add <SOURCE> <TARGET>

Add a port forwarding rule mapping a public source to a private target.

• --label <LABEL> — Human-readable label

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.

Updates

start-tunnel update check

Check the registry for available updates.

• --format — Output format

start-tunnel update apply

Apply an available update.

• --format — Output format

Server Management

start-tunnel restart

Reboot the StartTunnel server.

Web Interface

Manage the admin web UI.

start-tunnel web init

Initialize the web UI (interactive setup).

start-tunnel web uninit

Remove web UI configuration.

start-tunnel web enable

Enable the web UI.

start-tunnel web disable

Disable the web UI.

start-tunnel web set-listen <LISTEN>

Set the IP and port the web UI listens on.

start-tunnel web get-listen

Display the current listen address.

• --format — Output format

start-tunnel web generate-certificate [SUBJECT...]

Generate a self-signed TLS certificate for the web UI. Pass Subject Alternative Names for the certificate.

start-tunnel web import-certificate

Import a TLS certificate from stdin.

start-tunnel web get-certificate

Display the current TLS certificate.

• --format — Output format

start-tunnel web get-available-ips

List available IP addresses for binding.

• --format — Output format

Database

Low-level access to the StartTunnel database.

start-tunnel db dump [-p <POINTER>] [PATH]

Dump database contents, optionally filtered by JSON pointer.

• -p, --pointer <PTR> — JSON pointer to specific value
• --format — Output format

start-tunnel db apply <EXPR> [PATH]

Apply a patch expression to the database.

StartTunnel

StartTunnel is a virtual private router (VPR) — a minimal, self-hosted router that runs on a VPS instead of sitting in your house. Just like a home router, it creates private networks, assigns IP addresses to devices, and forwards ports to the public Internet. The difference is that it exists in the cloud, so it works regardless of your home network’s limitations.

• Clearnet hosting like Cloudflare Tunnels, but you control the router
• Private access like Tailscale, but fully self-hosted
• Dead simple — one command to install, manage everything from the CLI or web UI
• Open source — audit it, fork it, own it

Note

For setup instructions, see Installing.

Features

• 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

How StartTunnel Compares

StartTunnel occupies a unique position between Cloudflare Tunnel and Tailscale. All three solve the problem of connecting devices across the Internet, but they make fundamentally different trade-offs around trust, control, and convenience.

Architecture

StartTunnel is a virtual private router that runs on a VPS you control. Like a home router, it creates private networks, assigns IPs, and forwards ports — but using WireGuard tunnels instead of physical cables. Port forwarding uses kernel-level iptables NAT (Layer 3/4) to route public traffic to devices on the VPN. There is no central service, no coordination server, and no third party in the data path.

Cloudflare Tunnel runs a daemon (cloudflared) on your machine that makes outbound connections to Cloudflare’s global edge network. Public traffic hits Cloudflare’s CDN first, where Cloudflare terminates TLS, inspects the request at Layer 7, and proxies it to your origin through the tunnel.

Tailscale is a mesh VPN built on WireGuard. A proprietary coordination server (hosted by Tailscale Inc.) distributes keys and facilitates peer discovery, while actual traffic flows directly between devices. For public exposure, Tailscale Funnel routes traffic through Tailscale’s ingress servers, which terminate TLS.

Privacy and Trust

This is the most important difference. It comes down to: who can see your traffic?

StartTunnel: Nobody but you. Port forwarding operates at Layer 3/4 (iptables DNAT), meaning the VPS rewrites IP headers and forwards packets without inspecting payloads. If a service uses HTTPS, TLS terminates at the service itself — the VPS never sees plaintext. For VPN traffic between devices, WireGuard provides end-to-end encryption. Since you own the VPS, there is no third party with access to your traffic or metadata.

Cloudflare Tunnel: Cloudflare terminates TLS at their edge and re-encrypts to your origin. This means Cloudflare can — and does — see plaintext traffic. They offer “TLS inspection” as a feature and can scan request bodies, filter content, and inject responses. Using Cloudflare Tunnel requires trusting a publicly traded company not to misuse its position as a man-in-the-middle on all your traffic.

Tailscale: For device-to-device traffic, encryption is end-to-end — even Tailscale’s DERP relay servers forward encrypted packets they cannot read. However, the coordination server (run by Tailscale Inc.) sees metadata: which devices are connecting, their IPs, OS versions, and connection state. Tailscale explicitly states it is “not an anonymity service.” For public exposure via Funnel, Tailscale’s ingress servers terminate TLS, similar to Cloudflare.

Self-Hosting and Sovereignty

StartTunnel: Fully self-hosted. You rent a VPS, run the installer, and own the entire stack. No phone-home, no telemetry, no accounts, no dependency on any company’s infrastructure. If Start9 disappeared tomorrow, your tunnel would keep working.

Cloudflare Tunnel: The cloudflared client runs on your machine, but all traffic must route through Cloudflare’s proprietary global network. You cannot self-host the edge. If Cloudflare goes down — as happened in a 5.5-hour outage in November 2025 — your services go down with it.

Tailscale: The client is mostly open source, but the coordination server is proprietary. Headscale is a community-built open source alternative, but it reimplements a narrower scope (single tailnet) and is not maintained by Tailscale. By default, you depend on Tailscale Inc. for key distribution, peer discovery, and DERP relays.

Vendor Lock-In and Terms of Service

StartTunnel: MIT licensed. No terms of service. No content restrictions. No account that can be terminated. Use it however you want.

Cloudflare Tunnel: Cloudflare’s ToS prohibit streaming video or large file serving unless you use Cloudflare R2/Stream. Cloudflare reserves the right to terminate accounts “at any time, with or without notice for any reason or no reason at all.” Your services are one policy change away from going dark.

Tailscale: More permissive terms than Cloudflare, but you still depend on a company’s continued goodwill and operation. The free tier (3 users, 100 devices) has limits that paid tiers expand.

Comparison Table

What You Give Up

StartTunnel prioritizes sovereignty over convenience. That means:

• No DDoS protection — Your VPS IP is exposed on forwarded ports. Use your VPS provider’s DDoS protection, or place a CDN in front if needed.
• No global edge network — Traffic routes through one VPS, not a global CDN. Latency depends on VPS location.
• No built-in DNS — You manage your own DNS records.
• No identity provider integration — Authentication is key-based and password-based, not SSO.
• You manage the VPS — Minimal maintenance (Debian + one binary), but it’s yours to keep updated.

For many self-hosters, these trade-offs are not just acceptable — they’re the point.

Security

StartTunnel is built on WireGuard, a modern VPN protocol with a minimal, auditable codebase (~4,000 lines of code in-kernel).

• Encryption: ChaCha20-Poly1305 for symmetric encryption, Curve25519 for key exchange, BLAKE2s for hashing
• Pre-shared keys: Each peer connection uses an additional pre-shared key (PSK) for a layer of post-quantum resistance
• Key isolation: Private keys are generated on-device and never leave the device. Only public keys are exchanged.
• TLS passthrough: Port-forwarded traffic is not decrypted by the VPS. If your service uses HTTPS, TLS terminates at the service, not the tunnel.

Requirements

• Debian 12+ (Bookworm or newer)
• x86_64, aarch64, or riscv64
• Root access
• Public IP (required for clearnet port forwarding; not required for private VPN use)

Source Code

The StartTunnel source code and release binaries live in the StartOS monorepo. The start-tunnel repo hosts the installer script via GitHub Pages.

To report bugs or request features, open an issue.

FAQ

Answers to common questions about StartTunnel’s security model, compatibility, VPS requirements, and what happens if Start9 goes away.

Can anyone else see my traffic?

No. Port forwarding operates at Layer 3/4 (iptables DNAT), meaning the VPS rewrites IP headers and forwards packets without inspecting payloads. If your service uses HTTPS, TLS terminates at the service itself — the VPS never sees plaintext. For VPN traffic between devices, WireGuard provides end-to-end encryption. Since you own the VPS, there is no third party in the data path.

Do I need a WireGuard client on my devices?

Only for private access — phones, laptops, and other devices connecting to your server over the VPN. For clearnet hosting (exposing ports to the public Internet), no WireGuard client is needed on the devices accessing your services.

Can I run other services on the same VPS?

No. StartTunnel manages its own firewall rules and disables UFW. It is designed to be the sole application on the VPS.

Does StartTunnel work behind CGNAT?

Yes. WireGuard clients initiate outbound UDP connections, so CGNAT is not a problem for connecting devices to the VPN. Port forwarding still works because public traffic arrives at the VPS’s public IP.

What if I forget my password?

SSH into your VPS and run:

start-tunnel auth reset-password

What if Start9 goes away?

StartTunnel keeps working. It is fully self-hosted with no dependency on Start9 infrastructure. There is no coordination server, no telemetry, and no phone-home. The binary runs entirely on your VPS.

How do I remove StartTunnel?

StartTunnel is designed to run on a dedicated VPS. To remove it, simply destroy the VPS through your hosting provider. All WireGuard keys and configuration are stored on the VPS and will be removed with it.

What VPS providers work with StartTunnel?

Any provider that offers Debian 12+ with root access and a public IP. Common choices include Hetzner, DigitalOcean, Linode, Vultr, and OVH. Budget VPS providers (~$5/mo) work fine — StartTunnel has minimal resource requirements.

Does StartTunnel provide DDoS protection?

No. Your VPS IP is exposed on forwarded ports. Use your VPS provider’s built-in DDoS protection, or place a CDN in front if needed. See the Architecture page for a full comparison of trade-offs.