Skip to content

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 or clusto.app/account. Personal covers one user on up to 3 native devices with ongoing updates and is claimed without Stripe. See Accounts & Licensing for the full picture: plans, license keys, device management, and offline behavior.

The web client lives at 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, 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. 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. 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.

Clusto - remote AI coding agents over WebSocket.