Server overview

The tunnelctl server is the control plane. It owns tunnel reservations, authenticates callers, issues connection tokens, and orchestrates the FRP handshake at the edge. The CLI and any automation talk to it over HTTP.

Responsibilities

• Reservations — create, read, update, and delete tunnel records (protocol, slug or remote port, owner, target, enabled, state) for HTTP, TCP, and UDP tunnels.
• L4 port pool — manage the shared TCP/UDP port range: report the range, check a port, and allocate one (backs the CLI's ports helpers); HTTP slug availability backs slugs.
• Authentication & authorization — validate OIDC tokens and self-issued API keys, and enforce per-endpoint permissions.
• Connection tokens — mint and rotate the per-tunnel tokens the FRP client presents.
• FRP plugin — validate each proxy registration (signature, serial, protocol + slug or remote port) before the edge accepts it.
• Lifecycle — sweep expired Reserved/Inactive tunnels on a timer.

Shape of the service

It's a .NET (ASP.NET Core) service organized as vertical feature slices (Tunnels, API keys, Health, Meta, the FRP plugin). It persists to PostgreSQL in production (SQLite for local dev), exposes health probes and OpenAPI documents, and emits structured logs and OpenTelemetry traces.