DeskVNCServer - Anleitung

Erste Schritte

1. Ein Passwort festlegen

Öffnen Sie die Einstellungen (Zahnradsymbol, untere Werkzeugleiste) und tragen Sie ein VNC-Passwortein. Standard-VNC-Clients verwenden die DES-Challenge des RFB-Protokolls, die nur die ersten 8 ASCII-kompatiblen Bytes berücksichtigt — wählen Sie daher ein Passwort mit höchstens 8 Zeichen.

2. Den Server starten

1. Klicken Sie im Hauptfenster auf Start. Die Statusanzeige wechselt zu Läuft.
2. Vier Listener werden gleichzeitig gestartet: VNC 5900, QREX-Steuerung 5911, QREX-Medien 4010und die Datei-API 8766.
3. Klicken Sie auf Infos kopieren , um eine Zeile mit Host, Ports und aktueller PIN in die Zwischenablage zu kopieren.

3. Einen Client verbinden

Für einen Standard-VNC-Viewer (macOS Bildschirmfreigabe, RealVNC, TightVNC, mobile VNC-Apps):

1. Öffnen Sie den Viewer und geben Sie vnc://<your-mac-ip>:5900 als Adresse ein
2. Geben Sie das in Schritt 1 festgelegte VNC-Passwort ein
3. Steuern Sie Ihren Mac sofort — Tastatur, Maus, Kopieren/Einfügen über RFB

Für die App QuickRemote:

1. Öffnen Sie QuickRemote auf dem Smartphone oder Tablet und wählen Sie Add Mac
2. Geben Sie die 6-stellige Kopplungs-PIN ein, die DeskVNCServer anzeigt (oder scannen Sie den QR-Code, falls Ihre QuickRemote-Version das unterstützt)
3. QuickRemote speichert das zurückgegebene Bearer-Token und schaltet die erweiterten Funktionen frei — Eingabemethode, Audio, Zwischenablage-Abgleich und Dateiübertragung

Überblick über die Oberfläche

Statuszeile

Aktionsschaltflächen

• Start — Startet alle vier Listener.
• Stopp — Schließt jeden Listener und trennt aktive Sitzungen.
• Infos kopieren — Kopiert eine kurze Verbindungsübersicht (Host, VNC-Port, Steuerport, PIN) in die Zwischenablage, um sie bequem an einen Client weiterzugeben.

Verbindungsbereich

Zeigt den Bind-Host, die Ports, die aktuelle Server-ID und die aktive Kopplungs-PIN an. Der Text wird bei Änderungen an den Einstellungen automatisch aktualisiert.

Bereich „QuickRemote API“

Kurzreferenz zu den Protokollen, die der Server spricht. Listet die unterstützten RFB-Versionen, die Struktur der QREX-Endpunkte und den Befehlssatz der Eingabemethode auf, damit QuickRemote (oder Ihr eigener Client) weiß, was verfügbar ist.

Protokolle und Ports

Authentifizierung

• VNC-Clients — RFB-DES-Passwort (die ersten 8 ASCII-kompatiblen Bytes des eingestellten Passworts).
• QREX-Clients — Der anfängliche Austausch der 6-stelligen PIN unter POST /qr/v1/pair liefert ein Bearer-Token zurück. Jeder weitere QREX-HTTP-Aufruf und jeder WebSocket-Frame muss Authorization: Bearer <token>.
• Ist das VNC-Passwort leer, kündigt der Server den standardmäßigen RFB-Modus ohne Authentifizierung an. Nur für vertrauenswürdige LAN-Segmente sinnvoll.

Kurzreferenz der QREX-Endpunkte

GET  /qr/v1/capabilities    # öffentlich, liefert unterstützte Funktionen
POST /qr/v1/pair            # öffentlich, tauscht PIN gegen Bearer-Token
GET  /qr/v1/ws              # WebSocket, Authentifizierung nötig
POST /qr/v1/ime/get         # Authentifizierung nötig, aktive IME abfragen
POST /qr/v1/ime/list        # Authentifizierung nötig, verfügbare IMEs auflisten
POST /qr/v1/ime/set         # Authentifizierung nötig, IME wechseln
POST /qr/v1/ime/toggle      # Authentifizierung nötig, IME ein-/ausschalten
POST /qr/v1/ime/commit      # Authentifizierung nötig, Textstring übergeben

Einstellungen

Client-Beispiele

macOS Bildschirmfreigabe

1. Finder → Gehe zu → Mit Server verbinden
2. Geben Sie vnc://<your-mac-ip>:5900
3. Geben Sie das VNC-Passwort ein

cURL — Funktionen abfragen

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

cURL — koppeln und die IME-Brücke aufrufen

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

# 2. Text über die IME-Brücke übergeben
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 Bildrate und maximale Bildabmessungen, wenn Sie über ein langsames WLAN arbeiten oder die Verbindung durch ein VPN leiten.
• Koppeln Sie jedes Gerät einmal. Nach dem ersten PIN-Austausch übersteht das Bearer-Token Neustarts, sodass QuickRemote sich stillschweigend wieder verbindet.
• Verwenden Sie Infos kopieren als schnellen Weg, Verbindungsdaten per Chat oder E-Mail zu verschicken — es enthält alles, was ein Client braucht.
• Lassen Sie Dateiänderungen aktivieren aus, sofern Sie Uploads nicht wirklich brauchen. Der Nur-Lesen-Modus genügt, um Screenshots, Notizen oder Downloads durchzusehen.
• Deaktivieren Sie die Audio-API, wenn Sie sie nicht nutzen. Auch untätige Codecs kosten auf dem Encoder-Pfad etwas CPU-Leistung.

Fehlerbehebung

Der Server startet nicht

• Möglicherweise belegt bereits ein anderer VNC-Server (z. B. die macOS Bildschirmfreigabe) Port 5900. Beenden Sie ihn unter Systemeinstellungen → Allgemein → Freigabe, oder ändern Sie den Port in den Einstellungen von DeskVNCServer.
• Die Ports 5911 / 4010 / 8766 müssen alle frei sein. Prüfen Sie das mit lsof -i :5911 und Ähnlichem.

VNC-Clients scheitern an der Authentifizierung

• Achten Sie darauf, dass das Passwort höchstens 8 ASCII-kompatible Bytes hat. Mehrbyte-Zeichen oder längere Zeichenfolgen werden von der RFB-DES-Authentifizierung stillschweigend abgeschnitten.
• Wenn Sie bewusst kein Passwort möchten, lassen Sie das Feld leer und verbinden Sie sich mit einem Viewer, der VNC ohne Authentifizierung unterstützt.

QuickRemote lässt sich nicht koppeln

• Vergewissern Sie sich, dass Smartphone oder Tablet im selben WLAN wie der Mac sind.
• Öffnen Sie den Verbindungsbereich und lesen Sie die PIN erneut ab. Die PIN lässt sich in den Einstellungen neu erzeugen.
• Prüfen Sie die Firewall-Einstellungen von macOS — eingehende Verbindungen auf den QREX-Ports müssen erlaubt sein.

Die Fernsteuerung wirkt träge

• Senken Sie Bildrate und maximale Bildabmessungen in den Einstellungen.
• Deaktivieren Sie Funktionen, die Sie nicht nutzen (Audio, Zwischenablage, Eingabemethode), um CPU-Leistung freizugeben.

Dateien werden nicht übertragen

• Prüfen Sie, ob Dateiübertragung aktivieren aktiv ist. Nur-Lese-Auflistungen funktionieren ohne Dateiänderungen aktivieren.
• Wenn Uploads scheitern, aktivieren Sie zusätzlich Dateiänderungen aktivieren. Andernfalls beantwortet die Datei-API nur Leseanfragen.

Datenschutz

• Alle Sitzungen laufen direkt zwischen dem Client und Ihrem Mac. Es gibt kein Cloud-Relay, keine Telemetrie, keine Analysedaten.
• VNC-Passwort, QREX-Bearer-Token, Kopplungs-PIN und die stabile Server-ID werden ausschließlich in den lokalen App-Einstellungen gespeichert.
• Dateiänderungen sind standardmäßig deaktiviert. Entfernte Clients können nur lesen, bis Sie ausdrücklich Schreibrechte erteilen.
• Jede Erweiterung (Audio, Zwischenablage, Dateiübertragung, Eingabemethode, Ferneingabe) lässt sich jederzeit abschalten, um diese Fähigkeit sofort zu entziehen.
• Wenn der Server nur auf Ihrem Mac erreichbar sein soll, setzen Sie den Bind-Host auf 127.0.0.1.