Skip to content

Tunnels

A tunnel gives the agent a public address for its dashboard and private pages. Several backends can provide one, and one owner decides which runs.

Each backend implements TunnelProvider, and the manager treats them as interchangeable. A provider only starts its backend, reports the address and gives a way to stop it. It doesn’t decide about retries, fallback or notices.

TierBackendWhen it runs
1CloudflareNamedProvider, a persistent named tunnelTried automatically
1CloudflareQuickProvider, a zero-config Cloudflare quick tunnelTried automatically
2LocaltunnelProvider, a relay through *.loca.lt, and boreNever without the owner’s recorded approval

An address counts as active only after a request to /health through the public address succeeds. That stops a false “back online” message about a dead link.

TunnelLifecycle owns the sequence: detect a failure, attempt a start, fall back, notify, and heal itself. Every state change goes through one compare-and-swap, which refuses a change from a state the tunnel is no longer in.

TunnelNotifier keeps two channels apart. A group topic gets status text only, and never the address, the PIN or a signed link, because anyone in the group could read them and get around the owner’s consent. The owner’s private chat with the bot is the only channel that gets the address, the PIN and signed links.

GET /tunnel reports the current status.