TrollVNC: a VNC server that runs on a jailbroken or TrollStore iOS device

What TrollVNC does on the device

TrollVNC is a VNC server for iOS devices, allowing remote access to and control of the device's screen. The project description is short because the feature list is where the substance is.

Screen capture comes with scaling and frame rate control, and unchanged display frames are skipped on the device, so a static screen costs almost nothing to send. The wheel gestures are tunable with a natural direction toggle. The clipboard syncs in UTF-8 through the UltraVNC extension. Orientation is synchronised and input mapping is rotation-aware, so a phone turned on its side still maps touches to the right place.

There is an optional server-side cursor overlay, which matters for viewers that do not draw their own pointer. Authentication is classic VNC, with a full-access password and a separate view-only password, so you can let someone watch without letting them touch. A built-in HTTP and WebSockets server gives browser access with HTTPS and WSS supported, and Bonjour and mDNS advertisement makes the device discoverable by viewers on the local network.

Two more capabilities round it out. Reverse VNC lets the device connect out to a listening viewer instead of waiting for a connection, and managed configuration allows a pre-seeded setup for deployment across a fleet of devices.

The project is written in C and Objective-C, and it is packaged as a Theos project. The repository root has the usual Theos layout, with `app/`, `src/`, `include/`, `include-spi/`, `include-simulator/`, `lib/`, `lib-simulator/`, `PrivateFrameworks/`, `prefs/`, `layout/`, `devkit/` and `Artworks/`. The `prefs/` directory is the settings bundle, which is where the in-app Settings panel comes from, and `src/trollvncserver.mm` is the main entry point alongside separate Objective-C classes for the bulletin board, clipboard, screen capture, HID event generation and a memory warning observer.

The licence is GPL-2.0, and the last push was on 2026-10-14.

Running the server and the options that shape it

The documented usage has two paths. On a device you install the TrollVNC app from Releases and configure the server from Settings, then TrollVNC to match the options below. Or you run the server binary directly on the device or on a simulator:

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

The binding options are straightforward. `-b host` sets the bind address as an IPv4 or IPv6 literal, defaulting to all interfaces. `-p port` is the TCP port for VNC, default 5901. `-c port` is a TCP port for client management that listens on localhost only, and 0 disables it, which is the default. `-n name` sets the desktop name shown to clients, and `-v` puts the server in view-only mode, ignoring input.

The display controls are where the tuning lives. `-s scale` is the output scale factor, with 1 meaning no scaling and smaller values reducing output pixels. `-F spec` takes a single frame rate, a min-max range or a full min:preferred:max form, and the difference matters by iOS version. On iOS 15 and later a range is applied through `preferredFrameRateRange`, while on iOS 14 only `preferredFramesPerSecond` exists, so the maximum, or the preferred value if you gave one, is what you get.

`-A sec` is the keep-alive interval, which sends harmless dummy key events to stop the device sleeping. It only runs while at least one client is connected, the range is 15 to 86400 seconds, and 0 disables it.

The remaining groups cover input and network. `-W px` sets the wheel step in pixels per tick and 0 disables the wheel entirely, while `-w` takes a comma separated list of tuning keys such as step, coalesce, max, clamp, amp, cap, minratio, durbase, durk, durmin and durmax. `-N` inverts the wheel delta for natural scrolling, `-M` picks the modifier mapping between `std` and `altcmd`, and `-K` logs keyboard events with their keysym to stderr. `-H` starts the built-in HTTP server, `-D` sets its document root, and `-e` and `-k` point at an SSL certificate and key. `-B` toggles Bonjour advertisement, `-O` toggles orientation sync, `-E` toggles AssistiveTouch auto-activation, `-U` toggles the cursor overlay, `-i` and `-I` control the connect notifications, `-C` toggles the UTF-8 clipboard extension and `-T` toggles the TightVNC 1.x file transfer extension, which is off by default. `-V` is verbose logging and `-h` prints the built-in help.

A reasonable default session looks like this:

# Reduced output size and a 30 FPS capture cap
trollvncserver -p 5901 -n "My iPhone" -s 0.5 -F 30

# Native output size and a 60 FPS capture cap
trollvncserver -p 5901 -n "My iPhone" -s 1.0 -F 60

Note that the documentation says so explicitly: scaling to 0.5 reduces output pixels to approximately one quarter and cuts encoder input and potential network traffic, but capture still renders at native resolution. The scale control reduces what is encoded, not what is captured, so a slow device still pays the capture cost.

The input mapping turns touches into a mouse and keys into HID

The mapping table is the part that determines whether the tool feels usable, and it is where a VNC server for a phone differs most from one for a desktop.

The left mouse button is a single-finger touch, and holding it drags, with the move updating while held. The right button is the Home or Menu button, with a press treated as a short press and a hold as a long press, and the release ending it. The middle button is the power button, with the same press and hold semantics. The wheel is translated into short drags with coalescing and velocity, which is what the `-w` tuning keys adjust.

The keyboard is more capable than a phone keypad. Standard ASCII keys, Return, Tab, Backspace, Delete, the arrows, Home, End, PageUp, PageDown and function keys F1 through F24 are sent as HID keyboard usages, so they behave as real key presses in the target app rather than as character injection.

The modifier mapping has two schemes, and the difference is not cosmetic. Under `std`, which is the default, Alt becomes Option and Meta or Super becomes Command, matching iOS conventions. Under `altcmd`, which exists for macOS clients, Alt becomes Command, Meta becomes Option and Super becomes Command.

Media keys are translated too. When the client sends XF86 keysyms, brightness up and down adjust the display brightness, volume up, down and mute change the volume, and previous, play-pause and next map to track control.

The AssistiveTouch auto-activation under `-E on` is a small convenience with a careful implementation. When the first client connects, AssistiveTouch is enabled if it was off, and when the last client disconnects the previous state is restored, disabling it only if TrollVNC was the one that turned it on. That last clause is the important one, since a server that disabled AssistiveTouch on exit would strip an accessibility feature the user relies on. It applies on device builds and is a no-op on the simulator.

Reverse VNC, browser access and the state the switches leave behind

Reverse VNC changes the direction of the connection, which is the feature that makes the tool usable on networks where you cannot reach the device.

With `-reverse host:port` the device connects out to a listening VNC viewer, and the documentation names TightVNC and UltraVNC as the viewers that work. IPv6 addresses are written in bracketed form, for example `[addr]:port`. The second form, `-repeater id host:port`, connects out to an UltraVNC Repeater in Mode II with a numeric identifier, where host:port is the repeater's server or invers port, often 5500.

The cost of reverse mode is spelled out in the documentation and it is significant. When reverse is enabled, TrollVNC disables the local VNC port, the HTTP and WebSockets server, and Bonjour. So the moment you turn on reverse connection you give up browser access and local discovery in exchange for being able to connect outward through a firewall.

Browser access comes from the built-in HTTP server, which enables HTTP and WebSockets on a port given by `-H`, with `-D` setting the document root and `-e` and `-k` supplying an SSL certificate and key for HTTPS and WSS. The feature list calls out that secure WebSocket connections can be enabled without pain, which is a reasonable thing to advertise given how often the alternative is a certificate warning on every visit.

Discovery is `-B on|off`, which controls Bonjour and mDNS advertisement, and it is on by default. The notification switches are worth noting too, because they are the only signal a user gets that a session started. `-i on|off` sends a single user notification when the first client connects, and `-I on|off` controls notifications for every connect and disconnect. Both default to on.

One thing the documentation does not describe is how the server behaves with a full-access password unset, and it does not document a password rotation path or a rate limit on connection attempts. If you expose this beyond a trusted network, the classic VNC authentication and the address verification are the whole of your protection.

The Theos build and the libvncserver dependency

The build system tells you what this is underneath. The Makefile is a Theos package definition, and the version is stamped in directly with `export PACKAGE_VERSION := 3.2-272`, which matches the most recent release tag.

The target selection is where the iOS version support is decided. For a device build the architecture is arm64 and the target is `iphone:clang:16.5:14.0` by default, or `iphone:clang:16.5:15.0` when a package scheme is set. For the simulator the architectures are arm64 and x86_64 and the target is `simulator:clang:latest:15.0`, with the simulator root resolved by a script in `devkit/`. The scheme choice also feeds a compile definition, so a legacy build and a scheme build are genuinely different binaries rather than the same binary with a different name.

The sources are a mix of C and Objective-C++. The main file is `src/trollvncserver.mm`, and the supporting classes are separate translation units, one each for the bulletin manager, the clipboard manager, the screen capturer, the HID event generator and a memory pressure observer. The C flags include `-fobjc-arc`, and the C++ standard is set to c++20 through CCFLAGS. Device builds add `-march=armv8-a+crc`, which is a hint that the code uses the CRC32C instructions in the capture path.

The library list is the giveaway. Device builds link crypto and lzo2 alongside vncserver, and the simulator build links vncserver and z. The vncserver library is libvncserver, which is the standard open source VNC server library and where the RFB protocol handling, the UltraVNC and TightVNC extensions and the framebuffer encoding all come from. The lzo2 dependency on device builds is for the LZO compression encoding that the VNC protocol offers, and crypto covers the authentication and TLS pieces.

The include and library paths differ between the two targets too, with `include-spi/` and `lib/` used on device and `include-simulator/` and `lib-simulator/` on the simulator, and the simulator link adds the `PrivateFrameworks/` directory. Building against private frameworks is the reason the project is distributed through a jailbreak or TrollStore style channel rather than the App Store, and it is the practical constraint behind the whole installation story.

Where TrollVNC is the wrong choice, and its licence and release state

The first limit is the platform. The binary is a Theos package targeting arm64 iOS devices with a specific toolchain, and it links private frameworks, so it needs a jailbroken device or a TrollStore installation. The documentation does not describe an App Store build, and the topics on the repository, ios, jailbreak, trollstore and libvncserver, describe the intended distribution channel. A colleague on a stock iPhone simply cannot install it.

The second limit is the security model. Classic VNC authentication is a password scheme with no transport encryption built into the protocol, and the documented options for encryption are the separate HTTP and WebSockets server with an SSL certificate and key. A VNC port exposed on a network without a tunnel in front of it is a plaintext session with a password. Reverse mode, which exists precisely for locked-down networks, turns off the browser and discovery features to get there.

The third is the drift in the option list. The documentation points at PERFORMANCE.md for the pipeline analysis, the removed tuning controls and the device measurements, and the honest reading is that some knobs that used to exist are gone. The current list of what you can tune is shorter than the history of the project, so an old guide or an old script will pass flags the current binary no longer accepts. There is also a `compile-check.log` and a `compile-results.log` in the repository root, which suggests a build verification workflow, though the documentation does not describe what those logs cover.

Compare that with the remote support tools built for the purpose, which ship with an agent, an audit trail, a session consent prompt on the device and a managed service behind them. The difference in approach is that TrollVNC gives you a protocol, a device-side binary and no service, and the trade is that you get a screen on your desktop without giving a third party an account on your network, at the cost of owning the security decisions yourself.

On the licence, this is GPL-2.0 with the COPYING file in the repository root. GPL-2.0 is copyleft, so a distributed derivative carries the same terms, and the project publishes no home page, so the repository and its wiki are the whole of the project's presence. The releases are v3.1 on 2026-01-09, v3.1-2 on 2026-02-01 and v3.2-272 on 2026-04-18, the last push was on 2026-10-14, and the repository is not archived, so the tree is moving even though the newest tag is half a year old.

Editorial conclusion

TrollVNC fits a developer or tester who needs to see and drive an iOS screen from a desktop, whether that means reproducing a bug, demoing an app, or driving a device that is already jailbroken or running TrollStore. It does not fit an unmodified iPhone, since the binary is a Theos package built for arm64 device targets and depends on private framework interfaces, and it does not fit a remote support scenario, because the transport is classic VNC and the built-in HTTP server is for browser access rather than for hardened public exposure. Before you install it, build the package through the Build TrollVNC workflow rather than the simulator target, set a full-access password rather than leaving view-only mode as your only option, and read PERFORMANCE.md for the removed tuning controls, since the current options list is shorter than it once was.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. owngoal-dev/TrollVNC on GitHub
4. README
5. Releases