Connect to a remote server
Every client is a renderer over a cc_server that owns the data. The desktop can
run one inside itself; the web app at app.usectrl.dev
cannot, because a browser tab cannot host a server. Either way, this guide points
a client at a server running elsewhere — a small box, a cloud VM, a build server.
Prerequisites
Section titled “Prerequisites”- A running
cc_server. If you don’t have one, see Run a headless server. - Either the three pairing values the server minted — the server URL (
ws://…/rpcorwss://…/rpc), a device id and a pairing key — or a one-time invite code from a workspace admin, or an invite or pairing link that carries them. Redeeming an invite provisions your user, records your membership and mints this client’s credential for you, so you never handle a device id or key. Obtain these through a trusted channel and check the server fingerprint against a trusted QR or known pin on first connection.
Make sure the server is reachable
Section titled “Make sure the server is reachable”A local server needs nothing: ws://localhost:9030/rpc works from both the
desktop and the browser, because browsers treat loopback as a trustworthy origin.
A server on another machine is different. app.usectrl.dev is served over HTTPS,
so the browser will only open a wss:// socket with a certificate it already
trusts — and cc_server refuses to bind a non-loopback address without TLS in
the first place. Give it one of:
- a certificate directly, with
--tls-certand--tls-key - a TLS-terminating reverse proxy in front, with the server started
--insecure(plaintext between proxy and server at the outer listener, on a trusted network only; this does not disable the mandatory encrypted client session) - a tunnel or VPN that supplies the certificate — Tailscale, cloudflared, or similar. Settings → Server → Connection & status has the built-in tunnel opt-in under Share this server.
Two settings on the server side are easy to miss. Behind a proxy, NAT, or tunnel,
set --public-url to the address clients should actually dial — it defaults to
the local bind, so without it clients try the wrong host. And if you host your
own copy of the web build, add its origin to --allowed-origins, which defaults
to https://app.usectrl.dev alone; loopback and native clients are always allowed.
Connect the desktop app
Section titled “Connect the desktop app”On a fresh install:
- Launch Control Center. The first-run screen shows Welcome to Control Center.
- Click Connect to a server and enter the server URL, plus either an invite code or, under Use a pairing key, a device id and pairing key.
- Click Connect. Control Center dials the server and lands on the workspace inbox.
If you have an invite or pairing link, click Paste a pairing link instead and paste it. The dialog shows which server the link leads to. Check it, then click Connect: pasting alone never connects. If a connection fails, the dialog stays open with the error and everything you entered.
On a desktop that already runs its own server:
- Open Settings → Server → Connection & status.
- Click Add server. Enter the server URL (
wss://host:9030/rpc) and either an invite code or, under Use a pairing key, a device id and pairing key. The URL field’s suffix button discoverscc_serverinstances on your LAN or tailnet. - Click Connect, then Switch on the new server’s row.
Switching is live: the app rebuilds around the new session in place, with no restart. If the connect fails you stay on the current server and see the error. The row for the server you are on has no Switch action; the local server is the first row, labelled Run in this app.
Once switched, the desktop owns no database. Every screen reads and writes through the remote server over a signed, end-to-end-encrypted WebSocket session; the same protection applies on loopback and through the relay.
Connect the web client
Section titled “Connect the web client”The web build is always remote.
- Open app.usectrl.dev, or your own copy of the web build.
- Click Connect to a server and enter the server URL, plus either an invite code or, under Use a pairing key, a device id and pairing key. Paste a pairing link takes an invite or pairing link instead.
- Click Connect. The client dials the server and renders the same interface the desktop does.
If a pairing deep link is in the URL, the connect dialog opens with its fields filled in, so you can check the server before clicking Connect. The pairing key rides in the URL fragment, which browsers never send to the server hosting the page. Treat the link as a secret and trust the page serving the web client: the fragment does not protect against malicious page code.
What the browser does not do
Section titled “What the browser does not do”The web client reads and writes the same server as the desktop, but a few surfaces need a native window or the machine’s own devices:
- no OS notification toasts, notification sounds, or ambient banner rail (the in-app notification centre still works)
- no LAN or tailnet server discovery in the Add server dialog
- no in-app article reader — newsfeed articles open in a new tab
- no re-running a meeting summary and no cancelling one that is processing
Two behave differently rather than being missing. Meeting recording works in the browser, capturing your microphone plus a screenshare that includes an audio track. The button named after your editor (such as Open in VS Code) asks the server to launch the editor on the server’s display, so it is offered only to the server owner, and the button hides itself against a headless host with no editors installed.
Troubleshooting
Section titled “Troubleshooting”- Connection times out: the server must be reachable from the client. Check the bind (
--bind any), that the port is open and that--public-urlnames the address the client can actually dial. Over the open internet, TLS is mandatory — a plaintext non-loopback bind is refused at startup unless the server was started--insecurebehind a proxy. - The browser refuses to connect but a native client works: the browser’s origin is not on the server’s
--allowed-originslist. The default allows onlyhttps://app.usectrl.dev(plus loopback). - Server identity changed: the client rejects a fingerprint that differs from its saved pin. Verify the server’s identity out of band and re-pair through a trusted channel; do not ignore the warning or switch to an older/plaintext client.
- Pairing key rejected: re-run
cc_server pairon the server to rotate that device’s key, then enter the new one. A revoked device finds its credential gone and fails closed; revocation drops a live session within seconds. - Wrong workspace: the workspace is part of the URL (
/workspaces/:workspaceId/…) and travels with every call, so switching workspaces in one client changes only your own view. You can only reach workspaces you are a member of — anything else is refused with “Not a member of this workspace”. See Workspaces and isolation.
Related guides
Section titled “Related guides”- Run a headless server
- Pair a device: the phone relay path