Getting Started

Your first tunnel in minutes

Install from a release on a Linux server for production, or run from source for local development.

Install from a release Recommended · Linux

For a real deployment on a Linux server (Ubuntu/Debian and similar). The release bundle is self-contained — no .NET runtime required on the box.

1

Point DNS at your server

Add a wildcard record for tunnels and an A record for the management host:

*.tun.example.com   A   <your-server-ip>
app.example.com     A   <your-server-ip>
2

Download & install

Grab the latest Linux bundle and run the installer (replace OWNER/REPO with your repository):

curl -fsSL https://github.com/OWNER/REPO/releases/latest/download/ztpr-linux-x64.tar.gz | tar xz
sudo ./ztpr/install.sh

This creates the ztpr system user, installs to /opt/ztpr, writes a systemd unit, and starts the service.

sudo systemctl status ztpr
journalctl -u ztpr -f
No CI? Build the same bundle locally with pwsh deploy/build-release.ps1, then scp the resulting ztpr-linux-x64.tar.gz to the server, extract, and run chmod +x install.sh && sudo ./install.sh.
3

Register & configure

Open http://<your-server>/ and register. The first user becomes the admin. In Admin → Settings → General, set your base domain and app host, enable HTTPS, then restart:

sudo systemctl restart ztpr

Now issue a wildcard certificate on the HTTPS certificate tab. If you connect Amazon Route 53 on the DNS & Route 53 tab, the DNS records are created and verified automatically; otherwise the wizard shows the TXT records to add by hand. See the HTTPS & TLS guide for details.

Later users need an invite code (admins generate these under Admin → Invites), unless you turn the requirement off in Settings.
4

Create a key and connect the client

Under API keys, create a key — it's shown once (keys look like ztpr_…). Download the client from the Downloads page, then run it against your local service:

./ztpr --server https://app.example.com --key <your-key> --target http://localhost:3000

The client prints a public URL like https://royal-spruce.tun.example.com.

Run from source Development

For hacking on Ztpr locally. Requires the .NET 9 SDK. lvh.me resolves *.lvh.me to 127.0.0.1, so you get full ingress without DNS or TLS.

1

Run the relay

First-run defaults are BaseDomain=lvh.me, AppHost=localhost, HTTPS off — no configuration needed.

dotnet run --project src/Ztpr.Server --urls http://localhost:5000
2

Register and create a key

Open http://localhost:5000, register (first user = admin), then create an API key under API keys.

3

Start the client

With something running on localhost:3000:

dotnet run --project src/Ztpr.Client -- \
  --server http://localhost:5000 --key <your-key> --target http://localhost:3000

The client prints a URL like http://royal-spruce.lvh.me:5000 — open it to reach your local service through the tunnel.

Build self-contained client binaries with pwsh deploy/publish-clients.ps1 — they land in the server's wwwroot/downloads/, which the Downloads page links.