DeskVNCServer - Guida

Per iniziare

1. Imposta una password

Apri Impostazioni (icona a ingranaggio, barra in basso) e compila la VNC password. I client VNC standard usano il challenge DES di RFB, che rispetta solo i primi 8 byte compatibili ASCII: scegli una password lunga al massimo 8 caratteri.

2. Avvia il server

1. Nella finestra principale, clicca Start. L'indicatore di stato passa a Running.
2. Si attivano quattro listener contemporaneamente: VNC 5900, controllo QREX 5911, media QREX 4010 e file API 8766.
3. Clicca Copy Info per copiare negli appunti una riga con host, porte e PIN corrente.

3. Connetti un client

Per un viewer VNC standard (macOS Screen Sharing, RealVNC, TightVNC, app VNC mobili):

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

Per l'app QuickRemote:

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

Panoramica dell'interfaccia

Riga di stato

Pulsanti di azione

• Start: avvia tutti e quattro i listener.
• Stop: chiude tutti i listener e disconnette le sessioni attive.
• Copy Info: copia un breve riepilogo di connessione (host, porta VNC, porta di controllo, PIN) negli appunti, per condividerlo facilmente con un client.

Pannello di connessione

Mostra il bind host, le porte, il Server ID corrente e il PIN di pairing attivo. Il testo si aggiorna automaticamente quando cambiano le impostazioni.

Pannello QuickRemote API

Riferimento rapido ai protocolli parlati dal server. Elenca le versioni RFB supportate, la forma degli endpoint QREX e il set di comandi IME, cosi che QuickRemote (o il tuo client) sappia cosa e disponibile.

Protocolli e porte

Autenticazione

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

Riferimento rapido endpoint QREX

GET  /qr/v1/capabilities    # public, returns supported features
POST /qr/v1/pair            # public, exchange PIN for Bearer token
GET  /qr/v1/ws              # WebSocket, auth required
POST /qr/v1/ime/get         # auth required, query active IME
POST /qr/v1/ime/list        # auth required, list available IMEs
POST /qr/v1/ime/set         # auth required, switch IME
POST /qr/v1/ime/toggle      # auth required, toggle IME on/off
POST /qr/v1/ime/commit      # auth required, commit a text string

Impostazioni

Esempi di client

macOS Screen Sharing

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

cURL: scopri le capabilities

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

cURL: esegui pairing e chiama il IME bridge

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

# 2. Commit text via the IME bridge
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

• Riduci il frame rate e le dimensioni massime del frame quando sei su un Wi-Fi lento o stai instradando la connessione tramite una VPN.
• Esegui il pairing di ogni dispositivo una volta sola. Dopo lo scambio iniziale del PIN, il token Bearer sopravvive ai riavvii e QuickRemote si riconnette in modo silenzioso.
• Usa Copy Info come scorciatoia per inviare i dettagli di connessione via chat o email: include tutto cio che serve a un client.
• Lascia Enable file mutations disattivato a meno che tu non abbia davvero bisogno di upload. La modalita di sola lettura basta per scorrere screenshot, note o download.
• Disattiva l'audio API quando non lo usi. Anche fermi, i codec consumano un po' di CPU sul percorso di codifica.

Risoluzione dei problemi

Il server non si avvia

• Un altro server VNC (per esempio macOS Screen Sharing) potrebbe gia occupare la porta 5900. Fermalo da System Settings → General → Sharing, oppure cambia la porta nelle impostazioni di DeskVNCServer.
• Le porte 5911 / 4010 / 8766 devono essere tutte libere. Controlla con lsof -i :5911 e simili.

I client VNC non riescono ad autenticarsi

• Assicurati che la password non superi 8 byte compatibili ASCII. Caratteri multibyte o stringhe piu lunghe vengono troncati silenziosamente dall'autenticazione RFB DES.
• Se vuoi intenzionalmente non avere password, lascia il campo vuoto e collegati con un viewer che supporti la modalita no-auth di VNC.

QuickRemote non riesce a fare pairing

• Conferma che telefono o tablet siano sulla stessa Wi-Fi del Mac.
• Apri il pannello di connessione e rileggi il PIN. Il PIN puo essere rigenerato dalle impostazioni.
• Controlla le impostazioni del firewall macOS: le connessioni in ingresso sulle porte QREX devono essere consentite.

Il controllo remoto e a scatti

• Riduci il frame rate e le dimensioni massime del frame nelle impostazioni.
• Disattiva le funzionalita non in uso (audio, appunti, IME) per liberare CPU.

I file non vengono trasferiti

• Verifica che Enable file transfer sia attivo. Le elencazioni di sola lettura funzionano anche senza Enable file mutations.
• Se gli upload falliscono, abilita anche Enable file mutations. Altrimenti la File API risponde solo a richieste di lettura.

Privacy

• Tutte le sessioni si svolgono direttamente tra il client e il tuo Mac. Nessun relay nel cloud, nessuna telemetria, nessuna analitica.
• VNC password, token Bearer QREX, PIN di pairing e Stable Server ID sono memorizzati solo nelle impostazioni locali dell'app.
• Le file mutations sono disattivate per impostazione predefinita. I client remoti possono solo leggere finche non concedi esplicitamente l'accesso in scrittura.
• Puoi disattivare qualunque estensione (audio, appunti, trasferimento file, IME, input remoto) in qualsiasi momento per revocare immediatamente quella capacita.
• Per mantenere il server confinato al Mac, imposta il bind host a 127.0.0.1.