Skip to Content
DocsCloud OSServer ModePublic Tunnel

Public Tunnel

The Public Tunnel Manager lets you expose a service running on your Quazzar node to the public internet without port forwarding, a public IP, or a dedicated reverse-proxy VPS. Under the hood it supervises an frpc child process per tunnel and streams its output into a live log panel you can watch from the UI.

Two modes

Dock → Infra → Public Tunnel opens the Tunnel Manager. The New tunnel dialog has two tabs:

Self-hosted frps

Free on every plan. You run your own frps binary on a server that has a public IP (a $5/mo VPS is plenty). You fill in:

  • Relay server address — the host:port where your frps listens (default frps port is 7000).
  • Auth token — whatever you set for auth.token in your frps.toml.
  • Public hostname (optional for HTTP/HTTPS) — the subdomain you pointed at the frps.

Quazzar relay 🔒

Paid feature, gated by the orbit_public_tunnel flag (Orbit Pro or above — see Orbit Pro). When the plan includes it, the node asks the Quazzar Control Center to mint:

  • A fresh subdomain under *.tunnel.quazzar.cloud (8-char random prefix).
  • A single-use auth token.

Both are persisted on the node’s tunnels table and fed directly to the supervised frpc. No DNS configuration or relay provisioning on your side.

Installing frpc

Quazzar does not bundle the frpc binary — it’s resolved from $PATH at process-spawn time. Install it separately:

# Upstream release tarball (any distro)
curl -sSL https://github.com/fatedier/frp/releases/latest/download/frp_linux_amd64.tar.gz \
  | sudo tar -xz -C /usr/local/bin --strip-components=1 frp_linux_amd64/frpc
 
# Debian/Ubuntu via package
sudo apt install frp
 
# Arch
sudo pacman -S frp

The supervisor calls frpc --server-addr … --token … --name …. A missing binary surfaces as “[tunnel] failed to start: exec: “frpc”: executable file not found in $PATH” in the log panel.

Creating a tunnel

  1. Click New tunnel.
  2. Pick the mode tab.
  3. Fill in:
    • Name — a human-friendly label (e.g. my-ssh, staging-web).
    • Protocol — http, https, tcp, or udp.
    • Local address + port — the local target on this node (e.g. 127.0.0.1:8080).
    • Remote port — only for tcp/udp; the port the relay exposes (e.g. 2222 for SSH).
  4. Click Create tunnel. The row lands in the table and frpc is spawned immediately — no separate “apply” step.

Start, stop, delete

Each row has three controls:

  • Play / Pause — disable or re-enable the tunnel without deleting it. Stopped tunnels stay in the table for quick restart.
  • Logs — opens the live log panel below the table. Primed with the last ~200 lines from the supervisor’s ring buffer, then streams live via WebSocket.
  • Trash — stops frpc, deletes the row, and drops the ring buffer.

How supervision works

The supervisor runs one frpc goroutine per active tunnel:

  • Stdout + stderr are scanned line-by-line into a 200-line ring buffer.
  • Subscribers (the /ws/tunnels/{id} WebSocket) get primed with the ring-buffer snapshot on connect, then fan-out new lines in real time.
  • If frpc exits the supervisor sleeps with exponential backoff (1 s → 2 s → … → 30 s cap) and retries. This continues until you stop the tunnel explicitly.
  • On supervisor shutdown (e.g. node reboot) every child is killed gracefully.

Troubleshooting

“failed to start: executable file not found in $PATH” — install frpc; see above.

“exit status 1” right after start — frpc printed its error on stderr. Open the log panel; the most common cause is a wrong auth.token.

Tunnel shows “stopped” but I never pressed pause — a relay token may have been revoked server-side. For quazzar_relay tunnels, delete and recreate to mint a fresh token. For self-hosted, check your frps log.

The log panel is empty — either the child has nothing to say (idle protocol), or the WebSocket was killed by an intermediate proxy. The client reopens automatically; try switching to another tunnel and back.

Security considerations

  • Relay tunnels terminate TLS at frps by default. If you need TLS all the way to your node, use protocol https and run your service behind a TLS cert on the local port.
  • Tokens are stored on the node’s sqlite database and are never rendered in the UI — once created you can’t copy them back out.
  • Deleting a tunnel revokes the token on the node; if the relay issued it, the token becomes useless because the Control Center will reject authentications once the row is tombstoned.
Mail RelayFleet — App Migration