DeskVNCServer - Οδηγός

Getting Started

1. Set a Password

Open Settings (gear icon, bottom toolbar) and fill in VNC password. Standard VNC clients use the RFB DES challenge, which only honors the first 8 ASCII-compatible bytes — pick a password no longer than 8 characters.

2. Start the Server

1. On the main window, click Start. The status indicator flips to Running.
2. Four listeners come up at once: VNC 5900, QREX control 5911, QREX media 4010, and the file API 8766.
3. Click Copy Info to copy a one-liner with the host, ports, and current PIN to your clipboard.

3. Connect a Client

For a standard VNC viewer (macOS Screen Sharing, RealVNC, TightVNC, mobile VNC apps):

1. Open the viewer and enter vnc://<your-mac-ip>:5900 as the address
2. Type the VNC password you set in step 1
3. Control your Mac immediately — keyboard, mouse, copy/paste over RFB

For the QuickRemote app:

1. Open QuickRemote on the phone or tablet, choose Add Mac
2. Enter the 6-digit pairing PIN shown by DeskVNCServer (or scan the QR code if your QuickRemote build supports it)
3. QuickRemote stores the returned Bearer token and unlocks the extended features — IME, audio, clipboard sync, and file transfer

Interface Overview

Status Row

Action Buttons

• Start — Bring up all four listeners.
• Stop — Close every listener and disconnect active sessions.
• Copy Info — Copy a short connection summary (host, VNC port, control port, PIN) to the clipboard for easy sharing with a client.

Connection Panel

Displays the bind host, ports, current Server ID, and the active pairing PIN. The text is auto-refreshed when settings change.

QuickRemote API Panel

Quick reference for the protocols the server speaks. Lists the RFB versions supported, the QREX endpoint shapes, and the IME command set so QuickRemote (or your own client) knows what is available.

Protocols and Ports

Authentication

• VNC clients — RFB DES password (first 8 ASCII-compatible bytes of the configured password).
• QREX clients — Initial 6-digit PIN exchange at POST /qr/v1/pair returns a Bearer token. Every subsequent QREX HTTP call and WebSocket frame must include Authorization: Bearer <token>.
• If the VNC password is empty, the server advertises standard RFB no-auth mode. Useful for trusted LAN segments only.

QREX endpoint quick reference

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

Settings

Client Examples

macOS Screen Sharing

1. Finder → Go → Connect to Server
2. Type vnc://<your-mac-ip>:5900
3. Enter the VNC password

cURL — discover capabilities

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

cURL — pair and call the 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"}'

Tips

• Lower the frame rate and the maximum frame dimensions when you are on a slow Wi-Fi link or routing the connection through a VPN.
• Pair every device once. After the initial PIN exchange the Bearer token survives reboots, so QuickRemote reconnects silently.
• Use Copy Info as a quick way to send connection details over chat or email — it includes everything a client needs.
• Keep Enable file mutations off unless you really need uploads. The read-only mode is enough for browsing screenshots, notes, or downloads.
• Disable the audio API when you are not using it. Idle codecs still cost a small amount of CPU on the encode path.

Troubleshooting

The server will not start

• Another VNC server (e.g. macOS Screen Sharing) may already be on port 5900. Stop it from System Settings → General → Sharing, or change the port in DeskVNCServer's settings.
• Ports 5911 / 4010 / 8766 must all be free. Check with lsof -i :5911 and friends.

VNC clients fail to authenticate

• Make sure the password is at most 8 ASCII-compatible bytes. Multibyte characters or longer strings are silently truncated by the RFB DES auth.
• If you intentionally want no password, leave the field empty and connect with a viewer that supports VNC no-auth.

QuickRemote cannot pair

• Confirm that the phone or tablet is on the same Wi-Fi as the Mac.
• Open the Connection panel and re-read the PIN. The PIN can be regenerated from Settings.
• Check macOS firewall settings — incoming connections on the QREX ports must be allowed.

Remote control feels laggy

• Lower the frame rate and the maximum frame dimensions in Settings.
• Disable features you are not using (audio, clipboard, IME) to free up CPU.

Files do not transfer

• Confirm Enable file transfer is on. Read-only listings work without Enable file mutations.
• If uploads fail, also enable Enable file mutations. Otherwise the file API only responds to read requests.

Privacy

• All sessions run directly between the client and your Mac. There is no cloud relay, no telemetry, no analytics.
• The VNC password, QREX Bearer token, pairing PIN, and stable Server ID are stored in the local app settings only.
• File mutations are off by default. Remote clients can only read until you explicitly grant write access.
• Disable any extension (audio, clipboard, file transfer, IME, remote input) at any time to revoke that capability immediately.
• If you want to keep the server local to your Mac, set the bind host to 127.0.0.1.