The install script detects your platform and places one static binary in /usr/local/bin. It supports macOS and Linux.

$ curl -sSL https://www.subtunnel.dev/install.sh | sh

Manual download. Download the binary for your platform from GitHub Releases, extract it, and place it in your PATH.

Everything below runs on one small VPS. You need a domain and a server with ports 80, 443, and 7835 reachable.

1. 01

   Point DNS at your server

   Create A records for the tunnel domain and its wildcard, both pointing to your server's public IP address.

   DNS records

   A     tunnel.example.com      → 203.0.113.10
   A     *.tunnel.example.com    → 203.0.113.10

2. 02

   Install SubTunnel on the server

   SSH into the VPS and install the same static binary used by the client.

   $ curl -sSL https://www.subtunnel.dev/install.sh | sh

3. 03

   Generate a token

   Create a shared secret that clients will use to authenticate with the server.

   $ openssl rand -hex 16

4. 04

   Set up nginx TLS termination

   Use nginx to terminate TLS and forward HTTP traffic to SubTunnel's HTTP listener on port 8080.

   nginx.conf

   # Wildcard HTTPS routes *.tunnel.example.com to SubTunnel
   server {
       listen 443 ssl;
       server_name *.tunnel.example.com;
   
       ssl_certificate /etc/letsencrypt/live/tunnel.example.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/tunnel.example.com/privkey.pem;
   
       location / {
           proxy_pass http://127.0.0.1:8080;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }

   For wildcard certificates, use DNS-based validation with certbot: certbot certonly --dns-cloudflare -d tunnel.example.com -d *.tunnel.example.com.

5. 05

   Start the server

   Start the control plane on port 7835 and the internal HTTP listener on port 8080.

   $ subtunnel server --domain tunnel.example.com --token YOUR_TOKEN --port 7835 --http-port 8080

6. 06

   Run as a systemd service

   For production, run SubTunnel as a systemd service so it starts on boot and restarts automatically.

   /etc/systemd/system/subtunnel.service

   [Unit]
   Description=SubTunnel Server
   After=network.target
   
   [Service]
   Type=simple
   User=subtunnel
   ExecStart=/usr/local/bin/subtunnel server \
       --domain tunnel.example.com \
       --token YOUR_TOKEN \
       --port 7835 \
       --http-port 8080
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target

   Enable and start

   $ sudo systemctl enable subtunnel
   $ sudo systemctl start subtunnel
   $ sudo systemctl status subtunnel

7. 07

   Connect a client

   From your local machine, connect a port to the server and request its public subdomain.

   $ subtunnel local 3000 --to tunnel.example.com:7835 --token YOUR_TOKEN --subdomain myapp

Run the public server, connect one local port directly, start configured tunnels, or manage the client as a native service.

server = "tunnel.example.com:7835"
token = "YOUR_TOKEN"

[tunnels.myapp]
local_port = 3000
subdomain = "myapp"

$ subtunnel run --all
$ subtunnel run myapp --config /absolute/path/to/config.toml

$ subtunnel service install --config /absolute/path/to/config.toml
$ subtunnel service status
$ subtunnel service generate systemd --config /absolute/path/to/config.toml