DeskVNCServer - Anleitung

Erste Schritte

1. Passwort festlegen

Offnen Sie die Einstellungen (Zahnrad-Symbol in der unteren Werkzeugleiste) und tragen Sie das VNC password ein. Standard-VNC-Clients nutzen das DES-Challenge des RFB-Protokolls, das nur die ersten 8 ASCII-kompatiblen Bytes beachtet. Wahlen Sie ein Passwort mit hochstens 8 Zeichen.

2. Server starten

1. Im Hauptfenster auf Start klicken. Die Statusanzeige wechselt zu Running.
2. Vier Listener werden gleichzeitig gestartet: VNC 5900, QREX-Steuerung 5911, QREX-Media 4010 und die file API 8766.
3. Klicken Sie auf Copy Info, um eine Einzeiler-Zeile mit Host, Ports und aktuellem PIN in die Zwischenablage zu kopieren.

3. Client verbinden

Fur einen Standard-VNC-Viewer (macOS Screen Sharing, RealVNC, TightVNC, mobile VNC-Apps):

1. Offnen Sie den Viewer und geben Sie vnc://<your-mac-ip>:5900 als Adresse ein
2. Geben Sie das in Schritt 1 festgelegte VNC password ein
3. Steuern Sie Ihren Mac sofort: Tastatur, Maus, Kopieren/Einfugen uber RFB

Fur die QuickRemote-App:

1. Offnen Sie QuickRemote auf dem Telefon oder Tablet und wahlen Sie Add Mac
2. Geben Sie die 6-stellige Pairing-PIN ein, die DeskVNCServer anzeigt (oder scannen Sie den QR-Code, sofern Ihre QuickRemote-Version das unterstutzt)
3. QuickRemote speichert das erhaltene Bearer-Token und schaltet die erweiterten Funktionen frei: IME, Audio, Zwischenablage-Sync und Dateitransfer

Oberflachenubersicht

Statuszeile

Aktions-Buttons

• Start: Bringt alle vier Listener hoch.
• Stop: Schliesst alle Listener und trennt aktive Sitzungen.
• Copy Info: Kopiert eine kurze Verbindungsubersicht (Host, VNC-Port, Steuerport, PIN) in die Zwischenablage, um sie einfach mit einem Client zu teilen.

Verbindungspanel

Zeigt den Bind-Host, die Ports, die aktuelle Server ID und die aktive Pairing-PIN. Der Text wird bei Anderungen automatisch aktualisiert.

QuickRemote-API-Panel

Schnellreferenz fur die vom Server gesprochenen Protokolle. Listet unterstutzte RFB-Versionen, die Form der QREX-Endpunkte und den IME-Befehlssatz auf, damit QuickRemote (oder Ihr eigener Client) weiss, was verfugbar ist.

Protokolle und Ports

Authentifizierung

• VNC-Clients: RFB-DES-Passwort (erste 8 ASCII-kompatible Bytes des konfigurierten Passworts).
• QREX-Clients: Der initiale 6-stellige PIN-Austausch unter POST /qr/v1/pair liefert ein Bearer-Token. Jeder folgende QREX-HTTP-Aufruf und jeder WebSocket-Frame muss Authorization: Bearer <token> enthalten.
• Ist das VNC password leer, kundigt der Server den Standard-RFB-No-Auth-Modus an. Nur fur vertrauenswurdige LAN-Segmente sinnvoll.

Schnellreferenz QREX-Endpunkte

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

Einstellungen

Client-Beispiele

macOS Screen Sharing

1. Finder → Gehe zu → Mit Server verbinden
2. Tippen Sie vnc://<your-mac-ip>:5900
3. VNC password eingeben

cURL: Capabilities abfragen

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

cURL: Pairen und die IME bridge aufrufen

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

Tipps

• Senken Sie Frame-Rate und maximale Bildgrosse, wenn Sie uber eine langsame Wi-Fi-Strecke oder ein VPN routen.
• Pairen Sie jedes Gerat einmal. Nach dem initialen PIN-Austausch uberlebt das Bearer-Token Neustarts, sodass QuickRemote stillschweigend wiederverbindet.
• Verwenden Sie Copy Info als schnellen Weg, Verbindungsdetails per Chat oder E-Mail zu senden; es enthalt alles, was ein Client benotigt.
• Lassen Sie Enable file mutations aus, sofern Sie wirklich keine Uploads benotigen. Der Nur-lesen-Modus reicht zum Durchsehen von Screenshots, Notizen oder Downloads.
• Deaktivieren Sie die Audio API, wenn Sie sie nicht verwenden. Auch im Leerlauf kosten Codecs ein wenig CPU im Encode-Pfad.

Fehlerbehebung

Der Server startet nicht

• Moglicherweise belegt bereits ein anderer VNC-Server (z. B. macOS Screen Sharing) Port 5900. Stoppen Sie ihn unter System Settings → General → Sharing oder andern Sie den Port in den DeskVNCServer-Einstellungen.
• Die Ports 5911 / 4010 / 8766 mussen alle frei sein. Prufen Sie mit lsof -i :5911 und ahnlichen Befehlen.

VNC-Clients konnen sich nicht authentifizieren

• Stellen Sie sicher, dass das Passwort hochstens 8 ASCII-kompatible Bytes hat. Multibyte-Zeichen oder langere Zeichenketten werden von der RFB-DES-Authentifizierung stillschweigend abgeschnitten.
• Wenn Sie absichtlich kein Passwort wollen, lassen Sie das Feld leer und verbinden Sie sich mit einem Viewer, der VNC-No-Auth unterstutzt.

QuickRemote kann nicht pairen

• Bestatigen Sie, dass Telefon oder Tablet im gleichen Wi-Fi wie der Mac sind.
• Offnen Sie das Verbindungspanel und lesen Sie den PIN erneut ab. Die PIN lasst sich aus den Einstellungen neu generieren.
• Prufen Sie die macOS-Firewall-Einstellungen: eingehende Verbindungen auf den QREX-Ports mussen erlaubt sein.

Die Fernsteuerung wirkt traage

• Senken Sie Frame-Rate und maximale Bildgrosse in den Einstellungen.
• Deaktivieren Sie nicht genutzte Funktionen (Audio, Zwischenablage, IME), um CPU freizugeben.

Dateien werden nicht ubertragen

• Stellen Sie sicher, dass Enable file transfer aktiv ist. Nur-lesen-Auflistungen funktionieren auch ohne Enable file mutations.
• Schlagen Uploads fehl, aktivieren Sie zusatzlich Enable file mutations. Ansonsten beantwortet die File API nur Leseanfragen.

Datenschutz

• Alle Sitzungen laufen direkt zwischen Client und Ihrem Mac. Kein Cloud-Relay, keine Telemetrie, keine Analytics.
• Das VNC password, das QREX-Bearer-Token, die Pairing-PIN und die Stable Server ID werden ausschliesslich in den lokalen App-Einstellungen abgelegt.
• File mutations sind standardmassig aus. Remote-Clients konnen nur lesen, bis Sie explizit Schreibzugriff gewahren.
• Jede Erweiterung (Audio, Zwischenablage, Dateitransfer, IME, Remote-Eingabe) lasst sich jederzeit deaktivieren, um die Funktion sofort zu entziehen.
• Wenn Sie den Server lokal auf dem Mac halten mochten, setzen Sie den Bind-Host auf 127.0.0.1.