---
url: https://clusto.app/docs/web-client.md
description: Install and operate the Clusto browser client as a progressive web app.
---

# Web Client (PWA)

The Clusto app ships in three forms from one Vue codebase:

* the **desktop** Tauri shell (Windows / Linux / macOS),
* the **mobile** Tauri shell (Android), and
* a **standalone web client** - the same frontend compiled to static files,
  loaded in a regular browser and installable as a PWA / iOS home-screen app.

This page covers the web client: how it is built, how it is deployed, and the
one hard browser constraint you must satisfy for it to connect to your nodes.

## Sign-in requirement

The web client requires **signing in with a Clusto account that holds an active
license** - there is no per-device activation on the web (that exists only in
the desktop and mobile apps). Create and verify an account, then claim the
permanently free Personal plan at
[clusto.app/pricing](https://clusto.app/pricing) or
[clusto.app/account](https://clusto.app/account). Personal covers one user on up
to 3 native devices with ongoing updates and is claimed without Stripe. See
[Accounts & Licensing](/accounts-licensing) for the full picture: plans,
license keys, device management, and offline behavior.

The web client lives at **[web.clusto.app](https://web.clusto.app)**, its own
origin, separate from the clusto.app website. Because the two sites do not share
cookies, signing in on clusto.app does not sign you in here; sign in again inside
the web client (**Settings > Account**).

* **Email and password.** Signing in returns a session token that the web client
  keeps in this browser and sends as a bearer token on every request. The web client
  never uses cookies for your account. **Sign out** ends the session on the server
  and clears the stored token.
* **Continue with GitHub.** Goes through the Clusto sign-in page on clusto.app and
  returns to the web client with a one-time code that is tied to the browser that
  asked for it and used once. The code is exchanged for a session token over HTTPS,
  and it is never kept in the address bar or the diagnostics log. A sign-in link
  that is old, incomplete, or was not started from this web client shows "sign-in
  link is no longer valid" with a link back to the web client; start the sign-in
  again from there.
* **Sign in with browser.** Next to **Continue with GitHub**. Opens clusto.app,
  where you sign in with password plus 2FA code, a passkey, or GitHub, then confirm
  **Continue as** followed by your email; the web client is then signed in.
* **Accounts with two-factor authentication.** The web client cannot ask for the
  authenticator code itself, and there is no license-key activation on the web. An
  email-and-password sign-in on such an account is declined; use
  **Sign in with browser** or **Continue with GitHub** instead.
* **Session length.** A sign-in lasts 30 days from its last use. When it ends,
  Settings > Account says so and asks you to sign in again. Signing the browser out
  from the signed-in devices list on the account page, or resetting your password,
  ends it sooner.

Your connection profiles stay in the browser's local storage. Anything with access
to this browser profile (a browser extension, another person on a shared computer)
can read the stored session token, so sign out on devices you do not control.

## How it works

The web build is produced with Vite's `--mode web`. In that mode the Tauri API
modules (`@tauri-apps/api/core`, `event`, `app`, `window`) are aliased over the
browser shims in `crates/clusto-app/src/browser-shim/`, which talk **directly to
clustod over a WebSocket** - no Tauri runtime, no central backend. Connection
profiles are persisted in `localStorage`.

`vite-plugin-pwa` adds a web manifest, icons, and a service worker so the app is
installable. The service worker only precaches the app shell; it never touches
the daemon WebSocket (service workers don't intercept `ws://`/`wss://` traffic),
so there is no offline session mode - a live daemon connection is always
required.

The bundle is built for the root of its own origin (base path `/`, override with
`VITE_WEB_BASE`) and is hosted at `https://web.clusto.app`.

## Updates

The web client is published at `https://web.clusto.app` as one installable PWA
with its own service-worker scope. It used to live at `https://clusto.app/app`.
Those links and bookmarks, including the old `https://clusto.app/app-unstable/...`
URLs, redirect (301) to the same path on `web.clusto.app`, keeping the query
string. An installed copy of the old app retires itself the next time it checks for
an update: it clears its caches, unregisters, and moves the open window to
`web.clusto.app`. Browsers keep storage per origin, so the new address starts
without your old sign-in and saved connection profiles: sign in again and restore
the profiles from [Account Cloud Sync](/cloud-sync), or add them again. Reinstall the
home-screen app from the new address if you had one. There is no separate unstable
build.

When a newer build lands, the running app shows an
**Update available** banner with **Reload** and **Later** buttons; Reload
activates the waiting service worker and reloads onto the new build. An open PWA
re-checks for a new service worker about once an hour and again when it returns
to the foreground, so a shipped update surfaces promptly instead of only on the
browser's own (roughly daily) check.

## The HTTPS / `wss://` requirement

A browser will **not** let a page served over `https://` open a plain `ws://`
socket to a remote host - that is *active mixed content*, blocked by every
modern browser, and there is no override on iOS Safari. The only `ws://` target
allowed from an HTTPS page is `localhost`.

Because the web client is served over HTTPS (required for a service worker /
installable PWA), **every node it connects to must serve `wss://`** - i.e. clustod
must terminate TLS. Enable it per node in the daemon config:

```toml
# config.toml
tls_cert = "/path/to/fullchain.pem"
tls_key  = "/path/to/privkey.pem"
```

With both set, clustod listens on `wss://<addr>/ws` instead of `ws://`. There is
**no manual "Use TLS" toggle** in the connection form: the app auto-negotiates
the scheme. On an HTTPS page only `wss://` is possible (the browser forbids plain
`ws://`), so it uses that; on an HTTP page it tries `ws://` and `wss://` and
caches the working scheme per profile, switching to `wss://` for good once it has
worked. Just enter the node address. A node address must be a plain `host` or
`host:port`; anything with a path, query, or `@` in it is not dialed unencrypted.

The desktop and mobile apps and the CLI connect to nodes over TLS that pins the
node's own key and need no certificate. Browsers cannot pin a key, so the web
client needs the node certificate described here, or the relay below.

> `wss://` requires connecting by the node's **Tailscale MagicDNS hostname**
> (e.g. `my-node.tailnet.ts.net`), **not a bare IP** - the certificate is issued
> for that hostname, so an IP address fails TLS validation.

Because of this, the HTTPS web client steers you towards **Tailscale
`*.ts.net` domains**: they are the no-DNS, no-paperwork path to a
browser-trusted certificate. Any node reachable at its own public domain with a
valid certificate works too - Tailscale is just the easy default. The connection
form warns (but does not block) when the host you enter is neither a `*.ts.net`
name nor `localhost`.

Licensed accounts have a third option that skips TLS setup entirely:
[Clusto Tunnel](/clusto-tunnel). Nodes with the tunnel enabled are reachable from
the web client through a cloud relay on the same HTTPS origin
(`wss://web.clusto.app/relay`), no `wss://` or certificate on the node required.

The relay needs two things from you:

* **A sign-in in the web client.** The web client passes your session token to
  the relay when it opens the connection (as a WebSocket sub-protocol, never in
  the URL), and the relay checks your license with it. Without a sign-in the web
  client skips the relay route and says the relay needs a sign-in
  (**Settings > Account**). The relay limits how often one client can open
  connections (120 per minute); a client that reconnects in a tight loop is refused
  with HTTP 429 and has to wait out the rest of the minute.
* **A node linked to your account.** The relay only connects you to nodes that
  your account has linked, so a stranger who learns a node's tunnel address cannot
  reach it through the relay. The Clusto app links each node it connects to
  automatically while signed in to the same account. A node you reach only from a
  browser can be linked by running `clusto daemon link` on it (with `sudo` when
  the daemon runs as a service) and opening the link it prints. Linked nodes are
  listed, and can be unlinked, on the [account page](https://clusto.app/account).
  If the node is not linked, the connection fails with "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." Linking is free on
  every plan. You still need the node's token (or a pairing code) to connect.

### Getting a TLS domain for a node

**Easiest - the Clusto CLI.** Run this on the machine the daemon runs on. It
detects the node's Tailscale MagicDNS name, issues a cert with `tailscale cert`,
writes it next to the daemon config, sets `tls_cert`/`tls_key`, and restarts the
daemon:

```bash
sudo clusto cert --restart
# or, to issue for a specific name / skip the restart:
sudo clusto cert --name my-node.tailnet.ts.net
```

`clusto cert` reads the daemon's own config path automatically (and accepts an
explicit `--config <path>` if clustod runs with a non-default config). It **fails
fast with a clear message if Tailscale is not installed** on the node.

Requirements: the Tailscale CLI on `PATH` (override the binary with
`CLUSTO_TAILSCALE_BIN` for non-standard installs) and **HTTPS Certificates**
enabled for the tailnet (Tailscale admin console -> DNS -> HTTPS Certificates).
Tailscale certs expire after ~90 days, and the daemon renews them automatically:
it re-reads the certificate every hour and, when less than a third of its lifetime
is left (about 30 days), re-runs `clusto cert` itself (at most once every 12
hours). The new certificate is hot-reloaded into the running `wss://` listener
within the hour - no restart. Only certificates issued by `clusto cert` are
renewed this way; for a certificate you installed at another path, renew it
yourself (a changed file is still hot-reloaded) - the daemon logs a warning when
it is due. First-time enabling of TLS still needs a daemon restart
(`clusto cert --restart`).

**Manual - the Tailscale CLI.** Equivalent steps by hand:

```bash
sudo tailscale cert \
  --cert-file /etc/clusto/tls.crt \
  --key-file  /etc/clusto/tls.key \
  my-node.tailnet.ts.net
```

then set `tls_cert = "/etc/clusto/tls.crt"` / `tls_key = "/etc/clusto/tls.key"` in
the daemon config and restart clustod. Connect the web client to
`my-node.tailnet.ts.net:9178`; it negotiates `wss://` automatically.

> If you would rather not run TLS on nodes, serve the app over **http** instead
> of https. Plain `ws://` then works for nodes the browser may reach unencrypted.
> Served from `http://localhost`, the browser still treats it as a *secure
> context*, so the service worker / PWA install keep working too - you only lose
> those on a non-localhost HTTP origin (e.g. a LAN IP). See **Run locally over
> HTTP** below.

## Run locally over HTTP

The simplest way to reach nodes that don't terminate TLS is to serve the web
client yourself over plain HTTP on `localhost`:

```bash
pwsh ./scripts/clusto.ps1 serve        # build (root base) + serve on http://localhost:4173/
```

`http://localhost` is a browser *secure context*, so the service worker and PWA
install still work - but because it is **not** an HTTPS page, the browser lets it
open plain `ws://`. So you can connect to a node that has no `tls_cert`/`tls_key`
set; just enter the node address (e.g. `my-node.tailnet.ts.net:9178`) and the app
negotiates `ws://` automatically - there is no manual TLS toggle to flip.

Two safeguards apply to plain connections:

* **Unencrypted-connection consent.** A plain `ws://` connection sends the node
  token and every keystroke unencrypted. Loopback and Tailscale addresses connect
  without a prompt, because the node accepts those from any client. For any other
  host the web client asks first: a dialog explains that the connection is
  unencrypted, **Cancel** is the default, and **Connect unencrypted** remembers
  the choice for that host in this browser. Consent applies only to a plain
  `host` or `host:port` address, and a profile or link cannot grant it for you.
  Pairing codes also need a secure context (HTTPS, `localhost`, or the apps); on
  other plain pages use the node token.
* **The node may refuse.** Nodes refuse unencrypted requests for credentials from
  other machines unless the source is loopback, Tailscale, or listed under
  `[transport] plaintext_networks` in the node's `config.toml`. A refused connection
  shows "(host) refuses unencrypted connections from this network" and suggests the
  HTTPS web client with a node certificate, the Clusto Tunnel, or the desktop or
  mobile app.

Nodes also check the web page's own address. Your own nodes accept the hosted
`https://web.clusto.app` and the Clusto apps, but a daemon refuses a browser page
from any other origin (a connection from it gets HTTP 403) so that an arbitrary
website cannot talk to it. For a locally served or self-hosted web client, list its
origin once on each node and restart the daemon:

```toml
# config.toml (top level)
allowed_origins = ["http://localhost:4173"]
```

The command sets `VITE_WEB_BASE=/` so the bundle is served at the site root, then
runs `vite preview` with `--host` (also reachable on the LAN, though a LAN IP origin
is not a secure context and won't register the service worker, and its origin must
be added to `allowed_origins` too).

## Build

```bash
cd crates/clusto-app
pnpm build:web        # vue-tsc + vite build --mode web
```

Output lands in `crates/clusto-app/dist-web/` with the root (`/`) base path,
including `index.html`, hashed assets, `manifest.webmanifest`, `sw.js`, and the
icon set. Preview it locally with `pnpm preview:web`.

## Deploy

The build and deploy are wired into `scripts/clusto.ps1`.

```bash
# Build only (no publish) -> crates/clusto-app/dist-web
pwsh ./scripts/clusto.ps1 build web
```

The web PWA is served from its own origin, **`web.clusto.app`**, separate from the
`clusto.app` website and docs. The cloud deploy builds the web client with the root
base path and publishes it to that origin together with the rest of the site:

```bash
# Build + publish the cloud origins: landing, docs, accounts, and the PWA
pwsh ./scripts/clusto.ps1 deploy cloud
```

`dl.clusto.app` serves **only** binaries, release manifests, and `install.sh` -
no web assets.

Why a separate origin: the web client keeps your session token in the browser and
renders content written by agents, so it must not share cookies, storage, or
scripts with the website. `web.clusto.app` sends a strict content security policy
that allows only scripts served from the web client itself (no inline or `eval`
scripts), plus `nosniff`, no referrer, and strict transport headers, and it can be
framed only by itself (the design preview relies on that). It can still connect to
any `https:` or `wss:` address, because your nodes live at hostnames of your
choosing. The Clusto website sends CORS headers to the web client for the few
account and sync endpoints it needs, with the bearer token and without cookies,
and nothing else.

Setting up the origin is a one-time operator step. The web hosting setup needs a DNS
record for `web.clusto.app`, a staged web build, and a certificate, and it refuses
to switch `clusto.app` over until `https://web.clusto.app` answers. Run the cloud
deploy first, then the Oracle setup, back to back: after the cloud deploy the old
`/app` build can no longer sign in with GitHub or reach the relay.

Redeploys **overlay** the content-hashed `assets/` chunks rather than wiping
them, so a client still running the previous `index.html` can keep lazy-importing
its old-hash chunks after a ship; orphaned chunks past a grace window are pruned
so the folder stays bounded.

After publishing, the cloud deploy verifies that the public shell actually
advanced. It compares the SHA-256 hash of the staged `index.html` with the live
file at `https://web.clusto.app/index.html`. A stale nginx alias can still
return HTTP 200, but it cannot pass this content check. If the hashes differ,
the deploy fails and directs the operator to rerun the Oracle setup. The deploy
also checks that the script policy has no inline scripts, that
`https://clusto.app/app/...` answers with a 301 to the same path on
`web.clusto.app`, and that the relay endpoint responds.

Because it is a single-page app, the host must fall back to
`index.html` for unknown paths so a deep-link refresh doesn't 404. For nginx:

```nginx
location / {
    try_files $uri /index.html;
}
```

The old `https://clusto.app/app/` and `/app-unstable/` paths are not served any
more. They redirect to `web.clusto.app`, and only `sw.js` under them is kept so
installed copies of the old app can retire themselves. That worker and the
redirects are scheduled for removal after 2027-01-31.

## iOS install

On iPhone/iPad, open `https://web.clusto.app` in Safari, then **Share ->
Add to Home Screen**. The app launches fullscreen (no Safari chrome) using the
`apple-mobile-web-app-capable` meta tag and the apple-touch icon. Make sure the
nodes you connect to serve `wss://` (see above), or connections will be blocked.
