VNC server

Remotely control an iOS device using a keyboard and mouse

xcuitrunner contains an embedded VNC server which allows you to remotely control iOS devices using a keyboard and mouse.

Remotely controlling an iPhone using xcuitrunner and TightVNC

Enabling the VNC server

You must specify the --vnc option if you want to start xcuitrunner with the embedded VNC server. xcuitrunner will listen for VNC connections at port 5900. You can have xcuitrunner listen on another port by specifying the --vncPort option.

Connecting to the VNC server

To connect to the VNC server, have your VNC client using the following parameters:

Parameter Value
Server localhost or
Port 5900 or the value specified in --vncPort
Password The UDID of your device

Supported Clients

We’ve validated xcuitrunner with the following VNC clients:

  • TightVNC Viewer, a desktop-based VNC client for Windows
  • UltraVNC, a desktop-based VNC client for Windows and macOS
  • noVNC, a HTML5 VNC client. Requires websockify.
  • Guacamole, a clientless remote desktop gateway.

Hardware Keys

You can use the following special key codes to simulate clicking on hardware buttons:

Device Button Key Code Key Description
Home Button 0xffeb Super Left
Power Button (Lock/Unlock) 0x1008FF10 XF86XK_Standby
Volume Up 0x1008FF13 XF86XK_AudioRaiseVolume
Volume Down 0x1008FF11 XF86XK_AudioLowerVolume

For more information about the Quamotion xcuitrunner command-line utility, contact us at

Last modified January 21, 2020: Fix image URL (6c0dc42)