Start9/start-os
2
0
Fork 0
mirror of https://github.com/Start9Labs/start-os.git synced 2026-03-26 02:11:53 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7c772e873da824d1d53d6cb04eb380873ebe7ee6
start-os/START-TUNNEL.md
Matt Hill a9c9917f1a better ST instructions
2025-12-01 18:03:07 -07:00

4.7 KiB
Raw Blame History

StartTunnel

A self-hosted WireGuard VPN optimized for creating VLANs and reverse tunneling to personal servers.

You can think of StartTunnel as "virtual router in the cloud".

Use it for private remote access to self-hosted services running on a personal server, or to expose self-hosted services to the public Internet without revealing the host server's IP address.

Features

  • Create Subnets: Each subnet creates a private, virtual local area network (VLAN), similar to the LAN created by a home router.

  • Add Devices: When you add a device (server, phone, laptop) to a subnet, it receives a LAN IP address on that subnet as well as a unique WireGuard config that must be copied, downloaded, or scanned into the device.

  • Forward Ports: Forwarding a port creates a "reverse tunnel", exposing a specific port on a specific device to the public Internet.

Installation

  1. Rent a low cost VPS. For most use cases, the cheapest option should be enough.

    • It must have a dedicated public IP address.
    • For compute (CPU), memory (RAM), and storage (disk), choose the minimum spec.
    • For transfer (bandwidth), it depends on (1) your use case and (2) your home Internet's upload speed. Even if you intend to serve large files or stream content from your server, there is no reason to pay for speeds that exceed your home Internet's upload speed.

  2. Provision the VPS with the latest version of Debian.

  3. Access the VPS via SSH.

  4. Install StartTunnel:

TMP_DIR=$(mktemp -d) && (cd $TMP_DIR && wget https://github.com/Start9Labs/start-os/releases/download/v0.4.0-alpha.15/start-tunnel-0.4.0-alpha.15-a53b15f.dev_$(uname -m).deb && apt-get install -y ./start-tunnel-0.4.0-alpha.15-a53b15f.dev_$(uname -m).deb) && rm -rf $TMP_DIR && systemctl start start-tunneld && echo "Installation Succeeded"
  1. Initialize the web interface (recommended)

Updating

TMP_DIR=$(mktemp -d) && (cd $TMP_DIR && wget https://github.com/Start9Labs/start-os/releases/download/v0.4.0-alpha.15/start-tunnel-0.4.0-alpha.15-a53b15f.dev_$(uname -m).deb && apt-get install --reinstall -y ./start-tunnel-0.4.0-alpha.15-a53b15f.dev_$(uname -m).deb) && rm -rf $TMP_DIR && systemctl daemon-reload && systemctl restart start-tunneld && echo "Update Succeeded"

CLI

By default, StartTunnel is managed via the start-tunnel command line interface, which is self-documented.

start-tunnel --help

Web Interface

Enable the web interface (recommended in most cases) to access your StartTunnel from the browser or via API.

  1. Initialize the web interface.

    start-tunnel web init

  2. If your VPS has multiple public IP addresses, you will be prompted to select the IP address at which to host the web interface.

  3. When prompted, enter the port at which to host the web interface. The default is 8443, and we recommend using it. If you change the default, choose an uncommon port to avoid future conflicts.

  4. To access your StartTunnel web interface securely over HTTPS, you need an SSL certificate. When prompted, select whether to autogenerate a certificate or provide your own. This is only for accessing your StartTunnel web interface.

  5. You will receive a success message with 3 pieces of information:

    • https://IP:port: the URL where you can reach your personal web interface.
    • Password: an autogenerated password for your interface. If you lose/forget it, you can reset it using the start-tunnel CLI.
    • Root Certificate Authority: the Root CA of your StartTunnel instance.

  6. If you autogenerated your SSL certificate, visiting the https://IP:port URL in the browser will warn you that the website is insecure. This is expected. You have two options for getting past this warning:

Trusting your StartTunnel Root CA

  1. Copy the contents of your Root CA (starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----).

  2. Open a text editor:

    • Linux: gedit, nano, or any editor
    • Mac: TextEdit
    • Windows: Notepad

  3. Paste the contents of your Root CA.

  4. Save the file as ca.crt or ca.pem (make sure it saves as plain text, not rich text).

  5. Trust the Root CA on your client device(s):

Reference in New Issue View Git Blame Copy Permalink