---
url: https://clusto.app/docs/clusto-tunnel.md
description: >-
  Clusto Tunnel - reach your nodes without Tailscale or port forwarding. A
  premium feature that gives native apps direct encrypted P2P connectivity
  (iroh, QUIC hole-punching) and the web app a cloud relay fallback, enabled
  cluster-wide from Settings > Cluster.
---

# 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](/accounts-licensing)).

* **Native apps** (desktop and mobile) connect **directly, peer to peer**,
  using [iroh](https://www.iroh.computer/) 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.

1. 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.
2. 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](/node-identity), 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](#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:

1. It dials each saved endpoint over the tunnel, authenticating with the
   profile's cluster token (or its token if there is no cluster token).
2. It reads the cluster status the node pushes.
3. 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](/clustering#peer-transport)). 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 link` on it. It prints a
  `https://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](/cli#clusto-daemon-local-daemon-management).

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_url` in
  `config.toml` on every node rather than relying on it propagating.

## Configuration

The daemon side lives in `config.toml` under a `[tunnel]` section (see the
[Configuration reference](/configuration#full-config-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](/node-identity): 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_relays` being 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](/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.
