Tunnels & protocols
The tunnel model — HTTP slugs, TCP/UDP remote ports, public addresses, and lifecycle state.
A tunnel is a reservation that maps a public endpoint to a local service. Every tunnel
has a protocol — http, tcp, or udp — chosen when you start it
(up http|tcp|udp). The protocol decides how the tunnel is addressed and
how its public endpoint is rendered.
HTTP tunnels — addressed by slug
An HTTP tunnel is identified by a globally-unique slug, which becomes the subdomain of
its public URL: slug myapp → https://myapp.intunnel.eu. Slugs are DNS-safe:
- 3–32 characters
- lowercase letters, digits, and hyphens (
a-z,0-9,-) - must start and end with a letter or digit
Check availability before reserving with slugs check.
TCP / UDP tunnels — addressed by remote port
L4 tunnels (raw TCP and UDP) don't use a slug. Instead you pick a remote port from the server's shared pool, and the tunnel is exposed on the apex:
- TCP →
tcp.intunnel.eu:<remote-port> - UDP →
udp.intunnel.eu:<remote-port>
tunnelctl up tcp 27017 5432 # tcp.intunnel.eu:27017 → 127.0.0.1:5432
tunnelctl up udp 5353 53 # udp.intunnel.eu:5353 → 127.0.0.1:53The port must be inside the allowed range and free — use ports to see
the range (ports range), test a port (ports check), or grab a free one (ports pick).
Internally the server names an L4 tunnel tcp-<port> / udp-<port>; you only ever work
with the port number.
HTTP vs L4 addressing, at a glance
HTTP = one shared :443 edge, routed by hostname (<slug>.intunnel.eu). TCP/UDP =
a dedicated public port on the apex (tcp.intunnel.eu:<port>). That's why HTTP needs
a unique slug and L4 needs a free port.
What a tunnel holds
| Field | Meaning |
|---|---|
protocol | http, tcp, or udp |
slug / remotePort | public subdomain (HTTP) or public port (TCP/UDP) |
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 client has connected yet (short TTL). |
Active | A 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.