Server overview
The tunnelctl control plane — what it does and how it's built.
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 (slug, owner, target, enabled, state).
- 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, slug) before the edge accepts it.
- Lifecycle — sweep expired
Reserved/Inactivetunnels 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.
HTTP API
Endpoints, the reconciliation-friendly conventions, and how tunnels are mutated.
Deployment
How the server runs in the cluster, configuration, and health probes.
This section documents the service for operators and integrators. Day-to-day tunnel usage goes through the CLI.