DeskVNCServer - Handleiding

Aan de slag

1. Stel een wachtwoord in

Open Instellingen (tandwielpictogram, onderste werkbalk) en vul het VNC password in. Standaard VNC-clients gebruiken de RFB DES-challenge, die alleen de eerste 8 ASCII-compatibele bytes respecteert: kies een wachtwoord van maximaal 8 tekens.

2. Start de server

1. Klik in het hoofdvenster op Start. De statusindicator gaat naar Running.
2. Vier listeners komen tegelijk omhoog: VNC 5900, QREX-control 5911, QREX-media 4010 en de file API 8766.
3. Klik Copy Info om een eenregelige tekst met host, poorten en huidige PIN naar het klembord te kopieren.

3. Verbind een client

Voor een standaard VNC-viewer (macOS Screen Sharing, RealVNC, TightVNC, mobiele VNC-apps):

1. Open de viewer en voer vnc://<your-mac-ip>:5900 in als adres
2. Typ het VNC password dat je in stap 1 hebt ingesteld
3. Bedien je Mac meteen: toetsenbord, muis, kopieren/plakken via RFB

Voor de QuickRemote-app:

1. Open QuickRemote op telefoon of tablet en kies Add Mac
2. Voer de 6-cijferige pairing-PIN in die DeskVNCServer toont (of scan de QR-code als jouw QuickRemote-build dat ondersteunt)
3. QuickRemote bewaart het ontvangen Bearer-token en ontgrendelt de uitgebreide functies: IME, audio, klembordsync en bestandsoverdracht

Overzicht van de interface

Statusregel

Actieknoppen

• Start: brengt alle vier de listeners omhoog.
• Stop: sluit alle listeners en verbreekt actieve sessies.
• Copy Info: kopieert een korte verbindingssamenvatting (host, VNC-poort, control-poort, PIN) naar het klembord om eenvoudig met een client te delen.

Verbindingspaneel

Toont de bind host, de poorten, het huidige Server ID en de actieve pairing-PIN. De tekst wordt automatisch ververst wanneer instellingen veranderen.

QuickRemote API-paneel

Snelreferentie van de protocollen die de server spreekt. Toont de ondersteunde RFB-versies, de vorm van de QREX-endpoints en de IME-commandoset, zodat QuickRemote (of je eigen client) weet wat beschikbaar is.

Protocollen en poorten

Authenticatie

• VNC-clients: RFB DES-wachtwoord (eerste 8 ASCII-compatibele bytes van het geconfigureerde wachtwoord).
• QREX-clients: de initiele uitwisseling van de 6-cijferige PIN op POST /qr/v1/pair levert een Bearer-token op. Elke volgende QREX HTTP-aanroep en elk WebSocket-frame moeten Authorization: Bearer <token> bevatten.
• Is het VNC password leeg, dan kondigt de server de standaard RFB no-auth-modus aan. Alleen geschikt voor vertrouwde LAN-segmenten.

Snelreferentie QREX-endpoints

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

Instellingen

Voorbeeldclients

macOS Screen Sharing

1. Finder → Ga → Verbind met server
2. Typ vnc://<your-mac-ip>:5900
3. Voer het VNC password in

cURL: capabilities ophalen

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

cURL: pairen en de IME bridge aanroepen

# 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"}'

Tips

• Verlaag de frame rate en de maximale frame-afmetingen wanneer je op een trage Wi-Fi-verbinding zit of de verbinding via een VPN routeert.
• Pair elk apparaat eenmaal. Na de eerste PIN-uitwisseling overleeft het Bearer-token herstarts, zodat QuickRemote stilletjes opnieuw verbindt.
• Gebruik Copy Info als snelle manier om verbindingsgegevens via chat of e-mail te delen: het bevat alles wat een client nodig heeft.
• Houd Enable file mutations uit, tenzij je echt uploads nodig hebt. De alleen-lezen-modus volstaat voor het bekijken van screenshots, notities of downloads.
• Schakel de audio API uit wanneer je hem niet gebruikt. Codecs in rust kosten nog steeds wat CPU op het encodeerpad.

Probleemoplossing

De server start niet

• Mogelijk gebruikt een andere VNC-server (bijvoorbeeld macOS Screen Sharing) al poort 5900. Stop hem via System Settings → General → Sharing, of wijzig de poort in de DeskVNCServer-instellingen.
• De poorten 5911 / 4010 / 8766 moeten allemaal vrij zijn. Controleer met lsof -i :5911 en vergelijkbare commando's.

VNC-clients kunnen niet authenticeren

• Zorg dat het wachtwoord hoogstens 8 ASCII-compatibele bytes telt. Multibyte-tekens of langere strings worden stilzwijgend afgekapt door de RFB DES-authenticatie.
• Wil je opzettelijk geen wachtwoord, laat het veld dan leeg en verbind met een viewer die VNC no-auth ondersteunt.

QuickRemote kan niet pairen

• Controleer dat telefoon of tablet op dezelfde Wi-Fi zit als de Mac.
• Open het verbindingspaneel en lees de PIN opnieuw af. De PIN kan vanuit de instellingen opnieuw gegenereerd worden.
• Controleer de firewallinstellingen van macOS: inkomende verbindingen op de QREX-poorten moeten zijn toegestaan.

Bediening op afstand voelt traag

• Verlaag de frame rate en de maximale frame-afmetingen in de instellingen.
• Schakel ongebruikte functies (audio, klembord, IME) uit om CPU vrij te maken.

Bestanden worden niet overgedragen

• Controleer of Enable file transfer aanstaat. Alleen-lezen-overzichten werken zonder Enable file mutations.
• Mislukken uploads, schakel dan ook Enable file mutations in. Anders beantwoordt de File API alleen leesverzoeken.

Privacy

• Alle sessies lopen direct tussen de client en je Mac. Geen cloud-relay, geen telemetrie, geen analytics.
• Het VNC password, het QREX Bearer-token, de pairing-PIN en het Stable Server ID worden alleen in de lokale app-instellingen opgeslagen.
• Bestandsmutaties staan standaard uit. Remote clients kunnen alleen lezen totdat je expliciet schrijfrechten verleent.
• Schakel een uitbreiding (audio, klembord, bestandsoverdracht, IME, externe invoer) op elk moment uit om die mogelijkheid onmiddellijk in te trekken.
• Wil je de server tot je Mac beperken, stel dan de bind host in op 127.0.0.1.