DeskVNCServer - Guida

Per iniziare

1. Imposta una password

Apri le Impostazioni (icona a ingranaggio, barra degli strumenti in basso) e compila Password VNC. I client VNC standard usano la challenge DES di RFB, che considera solo i primi 8 byte compatibili con ASCII — scegli una password non più lunga di 8 caratteri.

2. Avvia il server

1. Nella finestra principale, fai clic su Avvia. L'indicatore di stato passa a In esecuzione.
2. Si attivano quattro listener contemporaneamente: VNC 5900, controllo QREX 5911, media QREX 4010e l'API file 8766.
3. Fai clic su Copia info per copiare negli appunti una riga con host, porte e PIN attuale.

3. Collega un client

Per un viewer VNC standard (Condivisione schermo di macOS, RealVNC, TightVNC, app VNC per dispositivi mobili):

1. Apri il viewer e inserisci vnc://<your-mac-ip>:5900 come indirizzo
2. Digita la password VNC impostata al passaggio 1
3. Controlla subito il tuo Mac — tastiera, mouse, copia/incolla via RFB

Per l'app QuickRemote:

1. Apri QuickRemote sul telefono o sul tablet e scegli Aggiungi Mac
2. Inserisci il PIN di abbinamento a 6 cifre mostrato da DeskVNCServer (oppure scansiona il codice QR se la tua versione di QuickRemote lo supporta)
3. QuickRemote memorizza il token Bearer restituito e sblocca le funzioni estese — IME, audio, sincronizzazione degli appunti e trasferimento di file

Panoramica dell'interfaccia

Riga di stato

Pulsanti di azione

• Avvia — Attiva tutti e quattro i listener.
• Arresta — Chiude ogni listener e disconnette le sessioni attive.
• Copia info — Copia negli appunti un breve riepilogo della connessione (host, porta VNC, porta di controllo, PIN) per condividerlo facilmente con un client.

Pannello Connessione

Mostra l'host di bind, le porte, il Server ID attuale e il PIN di abbinamento attivo. Il testo si aggiorna automaticamente quando cambiano le impostazioni.

Pannello API QuickRemote

Riferimento rapido ai protocolli supportati dal server. Elenca le versioni RFB supportate, la struttura degli endpoint QREX e il set di comandi IME, così QuickRemote (o un tuo client) sa cosa è disponibile.

Protocolli e porte

Autenticazione

• Client VNC — password DES di RFB (primi 8 byte compatibili con ASCII della password configurata).
• Client QREX — lo scambio iniziale del PIN a 6 cifre su POST /qr/v1/pair restituisce un token Bearer. Ogni successiva chiamata HTTP QREX e ogni frame WebSocket devono includere Authorization: Bearer <token>.
• Se la password VNC è vuota, il server annuncia la modalità RFB standard senza autenticazione. Utile solo su segmenti di LAN fidati.

Riferimento rapido agli endpoint QREX

GET  /qr/v1/capabilities    # pubblico, restituisce le funzioni supportate
POST /qr/v1/pair            # pubblico, scambia il PIN con un token Bearer
GET  /qr/v1/ws              # WebSocket, autenticazione richiesta
POST /qr/v1/ime/get         # autenticazione richiesta, interroga l'IME attivo
POST /qr/v1/ime/list        # autenticazione richiesta, elenca gli IME disponibili
POST /qr/v1/ime/set         # autenticazione richiesta, cambia IME
POST /qr/v1/ime/toggle      # autenticazione richiesta, attiva/disattiva l'IME
POST /qr/v1/ime/commit      # autenticazione richiesta, conferma una stringa di testo

Impostazioni

Esempi di client

Condivisione schermo di macOS

1. Finder → Vai → Connessione al server
2. Digita vnc://<your-mac-ip>:5900
3. Inserisci la password VNC

cURL — scoprire le funzioni disponibili

curl http://<your-mac-ip>:5911/qr/v1/capabilities

cURL — abbinamento e chiamata al bridge IME

# 1. Scambia il PIN con un token Bearer
TOKEN=$(curl -s http://<your-mac-ip>:5911/qr/v1/pair \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456"}' | jq -r .token)

# 2. Conferma il testo tramite il bridge IME
curl http://<your-mac-ip>:5911/qr/v1/ime/commit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello from remote"}'

Suggerimenti

• Abbassa la frequenza fotogrammi e le dimensioni massime del frame quando ti trovi su una connessione Wi-Fi lenta o instradi la connessione attraverso una VPN.
• Abbina ogni dispositivo una sola volta. Dopo lo scambio iniziale del PIN il token Bearer sopravvive ai riavvii, quindi QuickRemote si riconnette senza interventi.
• Usa Copia info come modo rapido per inviare i dettagli di connessione via chat o email — include tutto ciò che serve a un client.
• Lascia Attiva le modifiche ai file disattivato a meno che tu non abbia davvero bisogno dei caricamenti. La modalità di sola lettura basta per sfogliare screenshot, note o download.
• Disattiva l'API audio quando non la usi. Anche inattivi, i codec consumano un po' di CPU sul percorso di codifica.

Risoluzione dei problemi

Il server non si avvia

• Un altro server VNC (ad es. Condivisione schermo di macOS) potrebbe già occupare la porta 5900. Disattivalo da Impostazioni di Sistema → Generali → Condivisione, oppure cambia la porta nelle impostazioni di DeskVNCServer.
• Le porte 5911 / 4010 / 8766 devono essere tutte libere. Controlla con lsof -i :5911 e comandi simili.

I client VNC non riescono ad autenticarsi

• Assicurati che la password sia di al massimo 8 byte compatibili con ASCII. I caratteri multibyte o le stringhe più lunghe vengono troncati silenziosamente dall'autenticazione DES di RFB.
• Se vuoi intenzionalmente non usare alcuna password, lascia il campo vuoto e connettiti con un viewer che supporta la modalità VNC senza autenticazione.

QuickRemote non riesce ad abbinarsi

• Verifica che il telefono o il tablet sia sulla stessa rete Wi-Fi del Mac.
• Apri il pannello Connessione e rileggi il PIN. Il PIN può essere rigenerato dalle Impostazioni.
• Controlla le impostazioni del firewall di macOS — le connessioni in ingresso sulle porte QREX devono essere consentite.

Il controllo remoto sembra lento

• Abbassa la frequenza fotogrammi e le dimensioni massime del frame nelle Impostazioni.
• Disattiva le funzioni che non usi (audio, appunti, IME) per liberare CPU.

I file non vengono trasferiti

• Verifica che Attiva il trasferimento di file sia attivo. Gli elenchi in sola lettura funzionano anche senza Attiva le modifiche ai file.
• Se i caricamenti falliscono, attiva anche Attiva le modifiche ai file. Altrimenti l'API file risponde solo alle richieste di lettura.

Privacy

• Tutte le sessioni avvengono direttamente tra il client e il tuo Mac. Non c'è alcun relay cloud, nessuna telemetria, nessuna analisi.
• La password VNC, il token Bearer QREX, il PIN di abbinamento e il Server ID stabile sono memorizzati solo nelle impostazioni locali dell'app.
• Le modifiche ai file sono disattivate per impostazione predefinita. I client remoti possono solo leggere finché non concedi esplicitamente l'accesso in scrittura.
• Disattiva in qualsiasi momento una qualsiasi estensione (audio, appunti, trasferimento di file, IME, input remoto) per revocare immediatamente quella funzionalità.
• Se vuoi che il server resti locale al tuo Mac, imposta l'host di bind su 127.0.0.1.