Appearance
Clusto Tunnel
Clusto Tunnel lets clients reach a node without Tailscale, a VPN, or port forwarding. It is a premium feature: using it requires an active Clusto license (see Accounts & Licensing).
- Native apps (desktop and mobile) connect directly, peer to peer, using iroh with QUIC hole-punching. Traffic is end-to-end encrypted; relay servers only help set the connection up.
- The web app (the PWA at
web.clusto.app) cannot hole-punch from a browser, so it falls back to a cloud relay operated by Clusto.
The tunnel adds reachability, not access. Every connection through it still authenticates with the node's normal Clusto auth token, exactly like a direct connection. A node with the tunnel enabled but an unknown token is still closed to you.
Enabling it
The tunnel is off by default and enabled for the whole cluster at once, not node by node. It is license-gated.
- Open Settings > Cluster > Cluster Configuration. The Clusto Tunnel row has a single Enable for cluster button. Without an active license the button is disabled and shows a requires an active license hint.
- Click Enable for cluster and confirm in the dialog.
Confirming enables the tunnel everywhere in one step:
- The node you are connected to applies and persists the tunnel config. The tunnel endpoint id is the node's identity key, which every node already has.
- It fans the change out to every connected peer, which each apply and persist it too.
- Every node then self-restarts so its iroh endpoint binds. Active terminal sessions keep running across the restart; clients briefly reconnect.
There is no config.toml to edit, no port to open, and no relay URL to enter - the default relay is baked in. (An operator can still override the relay with [tunnel] relay_url in config.toml; see Configuration.)
Offline nodes converge automatically
A node that is offline when you toggle the tunnel is not left behind. Cluster config sync carries the tunnel flag with a last-writer-wins timestamp, so the moment such a node reconnects it applies the change and restarts itself. Nodes adopted into the cluster later converge the same way.
Disabling it
Once the tunnel is on, the same button reads Disable for cluster. Disabling follows the same path: the change is persisted, fanned out to peers, and every node restarts.
One thing to know before you disable: if a peer is currently reached over the tunnel, dropping the tunnel drops the link you reach it through. When that is the case, the confirm dialog warns you and names the nodes that may become unreachable until the tunnel is switched back on.
A node that is both offline and reachable only over the tunnel cannot be told to disable - it never receives the change. It stays enabled until it gains some other link (a direct, LAN, or Tailscale route) over which the disable can reach it.
Status
The Cluster Configuration card's Clusto Tunnel row shows the state as a badge:
- Disabled - the tunnel is off for this node.
- Enabled (restart pending) - the config is saved but the daemon has not yet finished restarting, so the endpoint is not bound.
- Active - the endpoint is bound and reachable.
When active, the row also shows the node's tunnel endpoint id - a 64-character hex public key - with a Copy id button. Nodes advertise this id to clients and peers automatically through cluster status, so there is nothing to configure on the client side.
Peer address pills - in the Cluster Configuration card and in the Cluster view - include a Clusto Tunnel pill when a node has a tunnel address. The highlighted pill is the route actually in use, so you can tell at a glance whether a peer is reached over the tunnel or a direct address.
When the app's own connection to its node runs over the tunnel, the connection status line in the nav sidebar header shows a radio-tower icon (Connected via Clusto Tunnel).
How connections are chosen
When the native app connects to a node it races every known route, and the first one to finish connecting wins:
- The tunnel leads. Tunnel endpoints are dialed first - the tunnel is the route that works from anywhere, so it gets the earliest start.
- Direct addresses follow. LAN, Tailscale, and other direct addresses join the same race 500 ms later (only when a tunnel route is racing; without one they start immediately). A direct address still wins whenever it connects before the tunnel does.
When the tunnel wins, the connection's address shows as iroh:<endpoint-id> in the app instead of a host and port.
Saved routes on every app
When a saved connection profile contains tunnel endpoint ids, desktop, mobile, and web always offer those routes during normal profile connections and reconnects. Route discovery does not wait for the client's locally cached account or license state, and it does not drop a saved tunnel route when that state is temporarily unavailable or out of date. This keeps auto-connect from stranding a mobile client that has no working direct route.
During a pinned-profile reconnect in the native desktop or mobile app, the pinned node's direct and tunnel routes get an 8-second head start. If none of them connects, routes for the profile's other cluster nodes join the same connection race. The head start ends early once every pinned route has failed, so a pinned node that is asleep or offline does not hold up the others.
When a fallback node answers first, the native app connects through it but keeps the pinned node as its home. It checks every 2 minutes whether the home node answers again and moves back to it once it does. The web app is unchanged.
Android and iOS do not let the tunnel see network changes or device sleep on its own, so the app tells it whenever the network may have moved: on returning after more than 10 s away, on online, on a Wi-Fi to cellular handover, and whenever the connection drops. A live tunnel connection then re-checks its paths at once, and the next tunnel dial runs on a freshly bound endpoint with a new relay connection, so a phone that wakes on the same network does not wait for a relay link that died while it slept. A tunnel dial that fails also refreshes the endpoint for the next attempt. Connections already open on the old endpoint keep working until they end. The reconnect remains one attempt from dialing through session loading, so a late route cannot replace and tear down a workspace that has already loaded.
The route uses the transport available on the current app:
- Desktop and mobile hand the saved endpoint to the native shell, which connects over iroh P2P.
- Web turns the same saved endpoint into an authenticated request to the Clusto cloud relay. The relay checks the signed-in account and active license when the connection opens.
Offering a route is not an authorization decision. Native tunnel access remains license-gated, and an unlicensed or signed-out browser relay request is refused by the relay rather than hidden by transient client-side state.
Finding nodes with Scan Network
In the native desktop and mobile apps, Connect > Scan Network also scans over Clusto Tunnel. Tunnel endpoint ids cannot be enumerated, so the scan starts from the tunnel endpoints saved in your connection profiles, including cloud-synced profiles:
- It dials each saved endpoint over the tunnel, authenticating with the profile's cluster token (or its token if there is no cluster token).
- It reads the cluster status the node pushes.
- It dials once more the tunnel endpoints of that node's cluster peers that no saved profile knew yet.
Nodes found this way are listed with a Clusto Tunnel source badge and an iroh:<endpoint-id> address. A node that a direct scan (Tailscale, LAN, localhost, Docker, subnet) also found is listed once, by its direct address. Picking a tunnel node opens the usual Connect dialog, with the token pre-filled when a saved profile knows that endpoint. iroh:<endpoint-id> is accepted as a connect address.
This matters where the app cannot read the Tailscale peer list: Android, macOS with the App Store Tailscale, or any device without Tailscale's CLI. Remote nodes such as a VPS never showed up in the scan there. Over the tunnel they do, as long as a saved profile knows the cluster.
A tunnel probe can take up to about 10 seconds per wave (hole-punching), so a scan with saved tunnel endpoints can take a little longer. The web app does not scan the tunnel, because browser relay connections are capped per account; it connects tunnel nodes through saved profiles as described above.
Node-to-node links
The tunnel also carries the cluster mesh itself: when both nodes have the tunnel available, their peer link runs over it. The tunnel is the preferred node-to-node route - it works from anywhere and survives IP changes - so a laptop with its VPN off, or a node behind a NAT with no Tailscale, stays a full cluster member.
How it works:
- When two nodes connect, each learns the other's tunnel endpoint id. If the link came up over a direct address first (direct TCP wins the initial race), the mesh dials the tunnel shortly after and upgrades the link to it; the direct route becomes the standing fallback. The old link keeps reading for 10 s after the switch, so replies and state updates still in flight are not lost.
- If the tunnel link dies (relay outage, endpoint restart), the mesh fails over to a direct address within seconds and keeps retrying the tunnel in the background, upgrading back once it answers.
- The tunnel address is persisted and gossiped with the node's other addresses, so peers can still dial a tunnel-only node after a daemon restart.
- Tunnel links are still peer-to-peer where possible: iroh hole-punches a direct QUIC path (including on the same LAN) and uses the relay only when hole-punching fails.
- Peer links over the tunnel use the same mutual, key-pinned authentication and cluster-token membership proof as direct peer connections (see Clustering). The tunnel endpoint id is the node's identity, so a tunnel link is pinned to the right node from the start.
Only the node being dialed needs the tunnel enabled - any node in the cluster can dial out to it, even nodes with their own tunnel switched off. In practice: enable the tunnel on the machines that leave your network (laptops, phones' home nodes), and the rest of the cluster keeps them in the mesh.
A node linked over the tunnel shows the Clusto Tunnel pill as its active address in cluster status, with its peer address as tunnel:<endpoint-id>.
The web relay
Browsers cannot do QUIC hole-punching, so the web client uses a cloud relay instead of direct P2P. It connects over WebSocket to wss://web.clusto.app/relay/connect?node=<endpoint-id>, authenticated by your signed-in Clusto account. The browser sends the account token in the WebSocket subprotocol header (never a cookie), so a page on another site cannot use your session to reach the relay.
The relay requires and enforces:
- A signed-in account with an active license. Without both, relay connections are refused.
- A node linked to your account. The relay only dials nodes registered to the account that is asking (see below). An unlinked node is refused before anything is dialed.
- At most 8 concurrent relay connections per account, and a limit on how fast one client can open new connections.
- A 120-second idle timeout - idle relay connections are closed and the app reconnects on demand.
The relay is a blind pipe: it forwards bytes between your browser and the node and cannot read or forge Clusto traffic. Clusto protocol authentication (the node token sent as the first message) still happens end to end between the browser and the node.
Which node the relay reaches
A node accepts web relay traffic only from the Clusto relay (or a relay you list in [tunnel] trusted_web_relays), on a dedicated protocol that cannot be used to reach it as a native client or a cluster peer. The relay tells the node an opaque identifier for your account, so the node rate-limits and logs each relay user separately: one account cannot lock the others out, and the node never sees your email address.
Linking a node to your account
For the relay to reach a node, the node must be linked to your Clusto account. A link is a short signed statement made by the node with its tunnel key, stored in your account. The Linked nodes card on your account page at clusto.app lists them, and you can Unlink any of them.
- Automatic. A signed-in desktop, mobile or web app that is connected to a cluster links every node with a tunnel endpoint that is not linked yet, once per app session. Any account that holds the node's token can link it, so a shared node can be linked to several accounts.
- From the node. If the only way to reach a node is the relay (no signed-in app can reach it), run
sudo clusto daemon linkon it. It prints ahttps://clusto.app/account/link-node#claim=...link valid for 10 minutes. Open it in a browser where you are signed in and confirm. Treat the link like a password until then;--node <uuid>signs for another node of the cluster and--cloud <url>points at a self-hosted cloud. See CLI Reference.
If a node is not linked, the web app shows: "This node is not linked to your Clusto account for web access. Open the Clusto app on a device that can reach it while signed in, or run clusto daemon link on the node." The relay closes such a connection with WebSocket close code 4403 (node-not-linked). A node still running an older release cannot be reached through the relay until it updates. Linking is free on every plan; the relay itself still needs the license.
Reliability
The tunnel recovers from transient failures on its own:
- Endpoint bind retries with backoff. If a node cannot bind its iroh endpoint at startup - for example the network is not up yet - it keeps retrying with backoff, so a boot-time network hiccup heals itself without intervention.
- Dials retry with backoff. A failed tunnel dial is retried on a backoff capped at 5 minutes, so a relay outage recovers automatically once the relay is back; you do not need to restart anything.
- One relay per cluster. All nodes in a cluster are expected to use the same relay. A custom relay hint learned from a peer is not persisted across a daemon restart, so if you run your own relay, set
[tunnel] relay_urlinconfig.tomlon every node rather than relying on it propagating.
Configuration
The daemon side lives in config.toml under a [tunnel] section (see the Configuration reference):
toml
[tunnel]
# Off by default. Enabled cluster-wide from Settings > Cluster; the daemon
# self-restarts to apply. You do not normally set this by hand.
enabled = true
# Optional override for the iroh relay used for connection setup and fallback.
# Defaults to the Clusto-hosted relay.
# relay_url = "https://relay.clusto.app:8443"
# Web relays allowed to forward signed-in browsers to this node, as endpoint ids
# (hex). Leave it out to trust only the Clusto relay; an empty list turns web
# relay access off. Only needed for a self-hosted or development relay. Read at
# startup, so a change needs a restart.
# trusted_web_relays = ["<relay endpoint id>"]The node's tunnel key is its identity key: it lives in identity.key in the data directory and is no longer part of config.toml. A [tunnel] secret_key from an older release is moved there on the first start, so the endpoint id stays the same.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Turns the tunnel listener on for this node |
relay_url | Option<String> | https://relay.clusto.app:8443 | Custom iroh relay URL for connection setup and fallback. The older https://relay.vazac.dev:8443 reaches the same relay, so a config that still names it keeps working |
trusted_web_relays | Option<Vec<String>> | the clusto.app relay | Endpoint ids (hex) of web relays allowed to forward browsers to this node; an empty list disables web relay access |
You normally never edit this by hand - the Enable for cluster button in Settings > Cluster writes it for every node.
Security model
- Unguessable endpoint. The tunnel endpoint id is an ed25519 public key (64 hex chars). Knowing it is required to even attempt a connection, and it cannot be enumerated.
- End-to-end encryption. iroh provides a TLS 1.3 encrypted, key-authenticated transport between the client and the node. The relay servers used for connection setup (and as the fallback path) cannot read or tamper with the traffic.
- Token auth unchanged. The tunnel only makes the node reachable. The client must still present the node's Clusto auth token, which the node verifies itself - the relay cannot bypass or forge that check.
- Web relay is pinned and owned. A node accepts the web relay protocol only from pinned relay identities, and the relay only dials nodes linked to the asking account. The relay's identity is pinned on each node, so a different relay cannot take its place without
trusted_web_relaysbeing changed.
Troubleshooting
State stuck on enabled (restart pending). Enabling the tunnel makes each node restart itself, so this state is normally brief and clears on its own once the daemon comes back and binds its endpoint. If it persists, the daemon did not finish restarting - check that clustod is running on that node and restart it if needed; the state then becomes active and the endpoint id appears.
Node unreachable through the tunnel. The tunnel does not keep an offline node reachable - if the node or its daemon is down, the tunnel is down with it. Check that the node is running and that [tunnel] enabled = true is active (state active, not restart pending).
Node shows offline in the cluster when only the tunnel is available. The node being dialed must have the tunnel active (not restart pending) - peer links run over the tunnel only toward nodes whose endpoint is bound. Confirm the tunnel is enabled cluster-wide, then let that node connect directly once (so peers learn its tunnel endpoint), after which the mesh reaches it through the tunnel from anywhere.
Web app: relay connection refused. The relay requires being signed in to your Clusto account with an active license. Sign in at the web app and check your license state under Settings > Account (see Accounts & Licensing). Free or expired accounts cannot use the relay.
Web app: "This node is not linked to your Clusto account" (close code 4403). The relay only reaches nodes linked to your account. Open the Clusto app on a device that can reach the node while signed in, wait a moment for the node to link (your account page at clusto.app lists linked nodes), or run sudo clusto daemon link on the node and open the link it prints. A node on an older release needs an update first. A self-hosted relay must be listed in the node's [tunnel] trusted_web_relays.
Web app: connections dropping or refusing to open. You may be at the 8 concurrent relay connections per-account cap - close unused tabs or devices. Idle relay connections are also closed after 120 seconds; the app reconnects automatically when you return.
Native app connects via iroh: although a direct path exists. This is expected: the tunnel starts first in the connection race, and direct addresses start 500 ms later, so the tunnel often wins. If the connection is slow, check that the direct path (same LAN, Tailscale up) answers; it wins whenever it connects first.