Connettiti a un server remoto

Ogni client è un renderer sopra un cc_server che possiede i dati. Il desktop può eseguirne uno al proprio interno; l’app web su app.usectrl.dev non può, perché una scheda del browser non può ospitare un server. In entrambi i casi, questa guida punta un client su un server in esecuzione altrove: una macchinetta, una VM nel cloud, un server di build.

Prerequisiti

Un cc_server in esecuzione. Se non ne hai uno, vedi Esegui un server headless.
O i tre valori di abbinamento generati dal server — l’URL del server (ws://…/rpc o wss://…/rpc), un ID dispositivo e una chiave di abbinamento — oppure un codice di invito monouso da un amministratore dello spazio di lavoro. Riscattare un invito esegue il provisioning del tuo utente, registra la tua appartenenza e genera per te la credenziale di questo client, quindi non devi mai gestire un ID dispositivo o una chiave.

Assicurati che il server sia raggiungibile

Un server locale non richiede nulla: ws://localhost:9030/rpc funziona sia dal desktop sia dal browser, perché i browser considerano il loopback un’origine affidabile.

Un server su un’altra macchina è diverso. app.usectrl.dev è servito in HTTPS, quindi il browser apre un socket wss:// solo con un certificato di cui si fida già — e cc_server rifiuta comunque di fare il bind di un indirizzo non di loopback senza TLS. Dagli una di queste opzioni:

un certificato diretto, con --tls-cert e --tls-key
un reverse proxy che termina il TLS davanti al server, avviato con --insecure (testo in chiaro dietro il proxy, solo su una rete affidabile)
un tunnel o una VPN che fornisce il certificato — Tailscale, cloudflared o simili. In Impostazioni → Server → Connessione e stato l’opt-in del tunnel integrato si trova sotto Condividi questo server.

Due impostazioni lato server sono facili da dimenticare. Dietro un proxy, un NAT o un tunnel, imposta --public-url sull’indirizzo che i client devono effettivamente contattare — il valore predefinito è il bind locale, quindi senza di esso i client provano l’host sbagliato. E se ospiti una tua copia della build web, aggiungi la sua origine a --allowed-origins, che per impostazione predefinita contiene solo https://app.usectrl.dev; il loopback e i client nativi sono sempre consentiti.

Connetti l’app desktop

Su un’installazione nuova:

Avvia Control Center. La schermata di primo avvio chiede Come eseguire Control Center?
Invece di Esegui in questa app, compila i campi di connessione: l’URL del server e, in alternativa, un codice di invito oppure un ID dispositivo e una chiave di abbinamento.
Fai clic su Connetti. Control Center contatta il server e atterra sulla posta in arrivo dello spazio di lavoro.

Su un desktop che esegue già un proprio server:

Apri Impostazioni → Server → Connessione e stato.
Fai clic su Aggiungi server. Inserisci l’URL del server (wss://host:9030/rpc) e, in alternativa, un codice di invito oppure un ID dispositivo e una chiave di abbinamento. Il pulsante di suffisso del campo URL rileva le istanze di cc_server sulla tua LAN o sul tuo tailnet.
Fai clic su Connetti, poi su Passa nella riga del nuovo server.

Il passaggio è dal vivo: l’app si ricostruisce attorno alla nuova sessione sul posto, senza riavvio. Se la connessione non riesce, resti sul server corrente e vedi l’errore. La riga del server su cui ti trovi non ha l’azione Passa; il server locale è la prima riga, etichettata Esegui in questa app.

Dopo il passaggio, il desktop non possiede alcun database. Ogni schermata legge e scrive attraverso il server remoto su una connessione WebSocket.

Connetti il client web

La build web è sempre remota.

Apri app.usectrl.dev o la tua copia della build web.
Inserisci l’URL del server e, in alternativa, un codice di invito oppure un ID dispositivo e una chiave di abbinamento.
Il client contatta il server e mostra la stessa interfaccia del desktop.

Se nell’URL è presente un deep link di abbinamento, i campi sono precompilati. La chiave di abbinamento viaggia nel frammento dell’URL, che i browser non inviano mai al server che ospita la pagina, quindi l’host statico non la vede mai.

Cosa non fa il browser

Il client web legge e scrive sullo stesso server del desktop, ma alcune superfici richiedono una finestra nativa o i dispositivi della macchina stessa:

niente toast di notifica del sistema operativo, suoni di notifica o barra dei banner ambientali (il centro notifiche in-app funziona comunque)
nessuna ricerca dei server su LAN o tailnet nella finestra Aggiungi server
nessun lettore di articoli in-app: gli articoli delle notizie si aprono in una nuova scheda
niente nuovo avvio di un riassunto di riunione e niente annullamento di uno in elaborazione

Due funzioni si comportano diversamente anziché mancare del tutto. La registrazione delle riunioni funziona nel browser e cattura il microfono più una condivisione dello schermo che include una traccia audio. Anche Apri in IDE funziona, ma chiede al server di avviare l’editor sul display del server, quindi il pulsante si nasconde su un host headless senza editor installati.

Risoluzione dei problemi

La connessione va in timeout: il server deve essere raggiungibile dal client. Controlla il bind (--bind any), che la porta sia aperta e che --public-url indichi l’indirizzo che il client può effettivamente contattare. Su internet aperto il TLS è obbligatorio: un bind non di loopback in chiaro viene rifiutato all’avvio, a meno che il server non sia stato avviato con --insecure dietro un proxy.
Il browser rifiuta di connettersi ma un client nativo funziona: l’origine del browser non è nell’elenco --allowed-origins del server. Il valore predefinito consente solo https://app.usectrl.dev (più il loopback).
Chiave di abbinamento rifiutata: riesegui cc_server pair sul server per ruotare la chiave di quel dispositivo, poi inserisci quella nuova. Un dispositivo revocato non trova più la sua credenziale e fallisce in modo restrittivo; la revoca interrompe una sessione attiva entro pochi secondi.
Spazio di lavoro sbagliato: lo spazio di lavoro fa parte dell’URL (/workspaces/:workspaceId/…) e viaggia con ogni chiamata, quindi cambiare spazio di lavoro in un client modifica solo la tua vista. Puoi raggiungere solo gli spazi di lavoro di cui sei membro: qualsiasi altro viene rifiutato con “Not a member of this workspace”. Vedi Spazi di lavoro e isolamento.

Guide correlate

Esegui un server headless
Associa un dispositivo: il percorso tramite relay per il telefono