Quickstart

This guide takes you from zero to a live public URL in a few minutes.

Prerequisites

A tunnelctl account on your organization's identity provider (SSO).
A local service listening on some port (e.g. a dev server on 8080).

1. Install

tunnelctl ships as a single self-contained binary (the FRP client is embedded — there's nothing else to install).

Download the binary for your platform, make it executable, and put it on your PATH:

install -m 0755 tunnelctl /usr/local/bin/tunnelctl
tunnelctl --help

A distroless image is published for amd64 and arm64:

podman run --rm oci.piblade.net/tunnelctl/tunnelctl-cli:latest --help

2. Log in

tunnelctl login

This opens your browser to the identity provider, and on success stores your tokens locally. On a headless box (SSH), use the device-code flow instead:

tunnelctl login --no-browser

Check who you are at any time:

tunnelctl whoami            # show identity + token expiry
tunnelctl whoami --verify   # also verify the tokens against the IdP and API

3. Expose a local service

Point a slug at a local port. The slug becomes your public subdomain.

tunnelctl up myapp 8080

myapp is now served at https://myapp.tunnelctl.eu, forwarding to 127.0.0.1:8080. The command runs in the foreground and streams logs — press Ctrl+C to shut the tunnel down cleanly.

Target formats

The target after the slug can be a bare port (8080 → 127.0.0.1:8080), a host:port (localhost:5173, [::1]:5173), or a URL (http://localhost:3000). Omit it entirely to reuse the target you used last time.

Run it in the background

To keep the tunnel up after you close the terminal, detach it as a daemon:

tunnelctl up myapp 8080 -d

The command returns immediately and the tunnel keeps running.

4. Inspect and stop

tunnelctl status        # tunnels running on this host (state, target, URL, uptime)
tunnelctl logs myapp    # view the daemon log for a tunnel
tunnelctl down myapp    # stop one tunnel
tunnelctl down --all    # stop every tunnel on this host

Next steps

Browse the full CLI reference.
Understand tunnels, slugs and state.
Learn how authentication works.