Tunnels & slugs
The tunnel reservation model — slugs, ownership, target, and lifecycle state.
A tunnel is a reservation that maps a public hostname to a local service. It is owned by the user who created it and identified by a slug.
Slugs
The slug is the subdomain of your public URL: slug myapp → myapp.tunnelctl.eu. Slugs
are DNS-safe and globally unique:
- 3–32 characters
- lowercase letters, digits, and hyphens (
a-z,0-9,-) - must start and end with a letter or digit
What a tunnel holds
| Field | Meaning |
|---|---|
slug | Public subdomain / identifier |
owner | The SSO subject + email of the creator |
targetPort | The local port traffic is forwarded to |
enabled | Whether the tunnel accepts connections |
state | Lifecycle state (below) |
| connection token serial | Monotonic counter used to invalidate old sessions |
Lifecycle state
A tunnel moves through a small state machine on the server:
| State | Meaning |
|---|---|
Reserved | Created, but no FRP client has connected yet (short TTL). |
Active | An FRP client is connected and forwarding traffic. |
Inactive | The client disconnected; a grace period runs before cleanup. |
Disabled | Explicitly paused by an admin; new connections are rejected. |
Automatic cleanup
Reserved tunnels that never activate, and Inactive tunnels that never reconnect, are
swept after a TTL. Active and Disabled tunnels are never auto-removed — they reflect
explicit intent.
Reconciliation-friendly by design
Tunnel reservations are managed through idempotent operations: creating a tunnel with the same desired spec twice converges to the same state, and deletes are idempotent too. This makes the API safe to drive from scripts, CLIs that retry, and IaC tooling. See Server & admin → API.