TrollVNC - VNC server for iOS

VNC server for iOS devices, allowing remote access and control of the device’s screen.

TrollVNC is a VNC server for iOS devices that allows remote access and control of the device’s screen. OwnGoalStudio develops it and provides extensive customization options for performance, display quality, and input handling.

Key features –

TrollVNC is a sophisticated VNC (Virtual Network Computing) server specifically designed for iOS devices. Unlike simpler VNC solutions, it offers advanced features like:

Battery optimization features
Intelligent dirty rectangle detection to reduce bandwidth
Configurable frame rates and scaling
Scroll wheel emulation
Clipboard synchronization
Password authentication

Usage

Run on device:

trollvncserver -p 5901 -n "My iPhone" [options]

Options

Basic:

-p port TCP port for VNC (default: 5901)
-n name Desktop name shown to clients (default: TrollVNC)
-v View-only (ignore input)
-A sec Keep-alive interval to prevent device sleep by sending harmless dummy key events; only active while at least one client is connected (15..86400, 0 disables, default: 0)
-C on|off Clipboard sync (default: on)

Display/Performance:

-s scale Output scale factor (0 < s <= 1, default: 1.0; 1 means no scaling)
-F spec Frame rate: single fps, range min-max, or full min:pref:max; on iOS 15+ a range is applied, on iOS 14 the max (or preferred) is used
-d sec Defer update window in seconds to coalesce changes (0..0.5, default: 0.015)
-Q n Max in-flight updates before dropping new frames (0..8, default: 2; 0 disables dropping)

Dirty detection:

-t size Tile size for dirty-detection in pixels (8..128, default: 32)
-P pct Fullscreen fallback threshold percent (0..100, default: 0; 0 disables dirty detection entirely)
-R max Max dirty rects before collapsing to a bounding box (default: 256)
-a Enable non-blocking swap (may cause tearing).

Scroll/Input:

-W px Wheel step in pixels per tick (0 disables, default: 48)
-w k=v,.. Wheel tuning keys: step,coalesce,max,clamp,amp,cap,minratio,durbase,durk,durmin,durmax
-N Natural scroll direction (invert wheel delta)
-M scheme Modifier mapping: std|altcmd (default: std)
-K Log keyboard events (keysym -> mapping) to stderr

Accessibility:

-E on|off Enable AssistiveTouch auto-activation (default: off)

Cursor & Rotation:

-U on|off Enable server-side cursor overlay (default: off)
-O on|off Sync UI orientation and rotate output (default: off)

HTTP/WebSockets:

-H port Enable built-in HTTP server on port (0 disables; default 0)
-D path Absolute path for HTTP document root
-e file Path to SSL certificate file
-k file Path to SSL private key file

Discovery:

-B on|off Enable Bonjour/mDNS advertisement for auto-discovery by viewers on the local network (default: on)

Logging:

-V Enable verbose logging (debug only)

Help:

-h Show built-in help message

Reverse Connection:

-reverse host:port Connect out to a listening VNC viewer (TightVNC/UltraVNC). IPv6 as [addr]:port.
-repeater id host:port Connect out to an UltraVNC Repeater (Mode II) with numeric id; host:port is the repeater’s server (invers) port (often 5500).

When reverse is enabled, TrollVNC disables the local VNC port (-p), HTTP/WebSockets (-H), and Bonjour (-B). See “Reverse VNC” below for full setup with examples.

Key Input Mapping

Mouse:

Left button: single-finger touch. Hold to drag; move updates while held.
Right button: Home/Menu button. Press = short press; hold ≈ long press. Release ends the press.
Middle button: Power button. Press = short press; hold ≈ long press. Release ends the press.
Wheel: translated into short drags with coalescing/velocity; see “Wheel/Scroll Tuning”.

Keyboard:

Standard ASCII keys, Return/Tab/Backspace/Delete, arrows, Home/End/PageUp/PageDown, and function keys F1..F24 are sent as HID keyboard usages.
Modifier mapping (-M):
- std (default): Alt -> Option; Meta/Super -> Command.
- altcmd (macOS): Alt -> Command; Meta -> Option; Super -> Command.
Media/consumer keys (when the client sends XF86 keysyms):
- Brightness Up/Down -> display brightness increment/decrement
- Volume Up/Down/Mute -> volume increment/decrement/mute
- Previous / Play-Pause / Next -> previous track / toggle play-pause / next track

Touch, scroll, and button mappings respect the current rotation when -O on is used.

AssistiveTouch auto-activation (-E on):

When the first client connects, TrollVNC enables AssistiveTouch if it’s currently off; when the last client disconnects, it restores the previous state (disables it only if TrollVNC enabled it).
Applies on device builds; no-op on the simulator.

Performance Tips

Quick guidance on key trade-offs (latency vs. bandwidth vs. CPU/battery):

-s scale: Biggest lever for bandwidth and encoder CPU. Start at 0.66–0.75 for text-heavy UIs; use 0.5 for tight links or slow networks; 1.0 for pixel-perfect.
-F spec: Cap preferred frame rate to balance smoothness and battery. 30–60 is a sensible range; on 120 Hz devices, 60 often suffices. On iOS 14 the max (or preferred if provided) value is used.
-d sec: Coalesce updates. Larger values lower CPU/bitrate but add latency. Typical range 0.005–0.030; interactive UIs prefer ≤ 0.015.
-Q n: Throughput vs. latency backpressure. 1–2 recommended. 0 disables dropping and can grow latency when encoders are slow.
-t size: Dirty-detection tile size. 32 default; 64 cuts hashing/rect overhead on slower devices; 16 (or 8) captures finer UI details at higher CPU cost.
-P pct: Fullscreen fallback threshold. Practical 25–40; higher values stick to rect updates longer. 0 disables dirty detection (always fullscreen).
-R max: Rect cap before collapsing to a bounding box. 128–512 common; too high increases RFB overhead.
-a: Non-blocking swap. Can reduce stalls/contension; may introduce tearing. Try if you see occasional stalls; leave off for maximal visual stability. If a non-blocking swap cannot lock clients, TrollVNC falls back to copying only dirty rectangles to the front buffer to minimize tearing and bandwidth.

Notes:

Scaling happens before dirty detection; tile size applies to the scaled frame. Effective tile size in source pixels ≈ t / scale.
With -Q 0, frames are never dropped. If the client or network is slow, input-to-display latency can grow.
On older devices, prefer lowering -s and increasing -t to reduce CPU and memory bandwidth.

Preset Examples

By default, dirty detection is disabled because it usually has a high CPU cost. You can enable it with -P to set a fullscreen fallback threshold.

Low-latency interactive (LAN):

trollvncserver -p 5901 -n "My iPhone" -s 0.75 -d 0.008 -Q 1 -t 32 -P 35 -R 512

Battery/bandwidth saver (cellular/WAN):

trollvncserver -p 5901 -n "My iPhone" -s 0.5 -d 0.025 -Q 2 -t 64 -P 50 -R 128

High quality on fast LAN:

trollvncserver -p 5901 -n "My iPhone" -s 1.0 -d 0.012 -Q 2 -t 32 -P 30 -R 512

Choppy network (high RTT/loss):

trollvncserver -p 5901 -n "My iPhone" -s 0.66 -d 0.035 -Q 1 -t 64 -P 60 -R 128

Older devices (CPU-limited):

trollvncserver -p 5901 -n "My iPhone" -s 0.5 -d 0.02 -Q 1 -t 64 -P 40 -R 256

Optional: add -a to any profile if you observe occasional stalls due to encoder contention; remove it if tearing is noticeable:

trollvncserver ... -a

Frame Rate Control

Use -F to set the CADisplayLink frame rate:

Single value: -F 60
Range: -F 30-60
Full range with preferred: -F 30:60:120

Notes:

On iOS 15+, the full range is applied via preferredFrameRateRange.
On iOS 14, only preferredFramesPerSecond is available, so the max (or preferred if provided) is used.

Keep-Alive (Prevent Sleep)

Use -A to periodically send a harmless dummy key event to keep the device awake while clients are connected.

Wheel/Scroll Tuning

The scroll wheel is emulated with short drags. Fast wheel motion becomes one longer flick; slow motion becomes short drags. You can tune its feel at runtime:

-W px: Base pixels per wheel tick (0 disables, default 48). Larger = faster scrolls.
-w k=v,... keys:
- step: same as -W (pixels)
- coalesce: coalescing window in seconds (default 0.03, 0..0.5)
- max: base max distance per gesture before clamp (default 192)
- clamp: absolute clamp factor, final max distance = clamp × max (default 2.5)
- amp: velocity amplification coefficient for fast scrolls (default 0.18)
- cap: max extra amplification (default 0.75)
- minratio: minimum effective distance vs step for tiny scrolls (default 0.35)
- durbase: gesture duration base in seconds (default 0.05)
- durk: gesture duration factor applied to sqrt(distance) (default 0.00016)
- durmin: min gesture duration (default 0.05)
- durmax: max gesture duration (default 0.14)
- natural: 1 to enable natural direction, 0 to disable

Examples:

Smooth and slow:

trollvncserver ... -W 32 -w minratio=0.3,durbase=0.06,durmax=0.16

Fast long scrolls:

trollvncserver ... -W 64 -w amp=0.25,cap=1.0,max=256,clamp=3.0

More sensitive small scrolls:

trollvncserver ... -w minratio=0.5,durbase=0.055

Disable wheel entirely:

trollvncserver ... -W 0

Clipboard Sync

Many VNC clients support clipboard sync, but behavior may vary. This feature is primarily supported by UltraVNC.

UTF-8 clipboard sync is enabled by default; fallbacks to Latin-1 for legacy clients where needed.
Starts when the first client connects and stops when the last disconnects.
Disable it with -C off if not desired.

Rotate / Orientation

When -O on is set, TrollVNC tracks iOS interface orientation and rotates the outgoing framebuffer to match (0°, 90°, 180°, 270°). Touch and scroll input are mapped into the device coordinate space with the correct axis and direction in all orientations.

Server-Side Cursor

TrollVNC does not draw a cursor by default; most VNC viewers render their own pointer. If your viewer expects the server to render a cursor, enable it with -U on.

Authentication

Classic VNC authentication can be enabled via environment variables:

TROLLVNC_PASSWORD: full-access password. Enables VNC auth when set.
TROLLVNC_VIEWONLY_PASSWORD: optional view-only password. When present, clients authenticating with this password can view but cannot send input.

Examples:

export TROLLVNC_PASSWORD=editpass
export TROLLVNC_VIEWONLY_PASSWORD=viewpass   # optional
trollvncserver -p 5901 -n "My iPhone"

Notes:

Classic VNC only uses the first 8 characters of each password.
You must set a password if you’re using the built-in VNC client of macOS.
-v forces global view-only regardless of password. View-only password applies per client.

HTTP / WebSockets

TrollVNC can start LibVNCServer’s built-in HTTP server to serve a browser-based VNC client, noVNC.

When -H is non-zero, the HTTP server listens on that port.
If -D is provided, its absolute path is used as httpDir. If omitted, TrollVNC derives a default httpDir relative to the executable ../share/trollvnc/webclients.
HTTP proxy CONNECT is enabled to support certain viewer flows.

Examples:

# Enable web client on port 5801 using the default web root
trollvncserver -p 5901 -H 5801

# Enable web client on port 8081 with a custom web root
trollvncserver -p 5901 -H 8081 -D /var/www/trollvnc/webclients

Using Secure WebSockets

WSS encrypts the WebSocket transport (TLS for ws).

Prerequisites:

A certificate (cert.pem) and private key (key.pem) accepted by your browser.
The built‑in HTTP server enabled on some port with -H (it also exposes the WebSocket endpoint).

Steps:

Generate or obtain a cert/key (example using a local CA on macOS).

brew install minica
minica -ip-addresses "192.168.2.100"

Trust the CA: import minica.pem into your OS/browser trust store (otherwise the browser will warn).

Copy the host cert and key to the device (choose any readable path).

scp -r 192.168.2.100 root@192.168.2.100:/usr/share/trollvnc/ssl/

Start TrollVNC with WSS enabled.

trollvncserver -p 5901 -H 5801 \
  -e /usr/share/trollvnc/ssl/192.168.2.100/cert.pem \
  -k /usr/share/trollvnc/ssl/192.168.2.100/key.pem

Connect from your browser. Open the bundled web page at http://<host>:5801/. The secure endpoint will be available when -e/-k are provided.

Notes:

The certificate must match what the browser connects to (IP or hostname/SAN).
Self‑signed setups require trusting the CA or the specific certificate.

Auto-Discovery (Bonjour/mDNS)

Publishes a VNC service on the local network via Bonjour/mDNS (type _rfb._tcp), using the name from -n and the port from -p.
Enabled by default. Toggle with -B on|off or in Settings → TrollVNC → “Enable Auto-Discovery”.
Viewers on the same LAN that support Bonjour can find it automatically; otherwise connect by ip:port shown in the app/logs.

Reverse VNC (Reverse Connection)

TrollVNC can initiate an outbound connection to a listening VNC viewer or an UltraVNC repeater. This avoids opening inbound ports on the device and is helpful behind NAT/firewalls.

When reverse connection is enabled:

The normal server listening port is disabled (equivalent to not using -p).
The built-in HTTP server is disabled (any -H is ignored).
Bonjour/mDNS advertisement is disabled.
Classic VNC authentication via environment variables still applies if set (see “Authentication”).

1) Viewer mode (Listening Viewer: TightVNC/UltraVNC)

TrollVNC can connect to a viewer running in Listening mode. The viewer listens for inbound reverse connections; TrollVNC dials out.

Roles and steps:

A) Viewer (Listening)

Start TightVNC or UltraVNC Viewer in “Listen” mode (UltraVNC: Connections → Listen mode, or Toolbar → Listen).
Default listening port is 5500; you can change it in the viewer options.
Ensure your desktop firewall allows inbound on the chosen listening port.

B) Server (TrollVNC, Viewer mode)

CLI examples (use your viewer’s listening host:port):# IPv4 trollvncserver -reverse 203.0.113.10:5500 -n “My iPhone” # IPv6 trollvncserver -reverse [2001:db8::1]:5500 -n “My iPhone”
Preferences (Settings → TrollVNC):
- Reverse Connection → Mode: Viewer
- Server: host:port (e.g., viewer.example.com:5500 or [2001:db8::1]:5500)

Notes:

Only an outbound TCP connection from the device to the viewer is required.
If your viewer uses a custom port, specify that port in -reverse host:port and in the Server field.
The desktop viewer shows the incoming reverse connection with the name from -n.

2) Repeater mode (UltraVNC Repeater, Mode II)

TrollVNC can connect to an UltraVNC Repeater in Mode II. Both the Server (TrollVNC) and the Viewer make outbound connections to the Repeater and pair via a numeric ID.

Roles and steps:

A) Repeater

Deploy or start an UltraVNC Repeater that both device and viewer can reach (public, DMZ, or with NAT port forwards).
Common defaults (may vary by setup):
- Server (invers) port: 5500
- Viewer port: 5901 (sometimes 5900)
Make a note of the repeater’s host:port for the Server side (often host:5500) and for the Viewer side (often host:5901).

B) Server (TrollVNC on iOS)

Choose a numeric Repeater ID (commonly up to 9 digits). Do not include ID: — enter only the number.
CLI example (use the repeater’s server port):trollvncserver -repeater 12345679 repeater.example.com:5500 -n “My iPhone”
- 12345679 is the numeric Repeater ID.
- repeater.example.com:5500 should point to the repeater’s server (invers) port. IPv6 example: -repeater 12345679 [2001:db8::1]:5500
Preferences (Settings → TrollVNC):
- Reverse Connection → Mode: UltraVNC Repeater
- Server: host:server_port (e.g., repeater.example.com:5500 or [2001:db8::1]:5500)
- Repeater ID: numeric (e.g., 12345679)

Behavior when reverse is enabled: local VNC port is disabled, HTTP/WebSockets are disabled, and Bonjour/mDNS is disabled.

Optional: set TROLLVNC_REPEATER_RETRY_INTERVAL (seconds) to wait before exit if the connection fails (useful when a supervisor always restarts the process).

C) Viewer (Client)

UltraVNC Viewer is recommended for Mode II:
- Select “Repeater”; in “ID:12345679”, enter ID:<your_id> (e.g., ID:12345679).
- Enter the repeater’s viewer address, e.g., repeater.example.com:5901.
- Connect; the repeater pairs the viewer with the server using the matching ID.

Notes:

Connections are outbound from both sides; no inbound port on the iOS device is needed.
Use the repeater’s server port for TrollVNC (-repeater <id> host:server_port) and the viewer port for UltraVNC Viewer.
UltraVNC “Mode SSL” repeaters require special viewer/server builds; TrollVNC connects to standard (non-SSL) Mode II repeaters.

Build Dependencies

See: https://github.com/Lessica/BuildVNCServer

Written By:

Michael Warner

Michael Warner is an award-winning tech journalist and iOS developer with over 25 years of experience in jailbreaking, Cydia, Sileo tweak creation, and mobile app innovation. As the founder of Zee iPA Library, he’s a trusted name in the iOS community. Based in Australia, he also blogs about sports and lifestyle, and is a proud father of two.