Pre-launch preview · purchasing opens soon

Documentation

Connect to a VNC server

All setup guides

TunnelConnect connects to any computer that runs a VNC server. This guide turns on a standard VNC server — on a Raspberry Pi, Linux or Windows — and adds the matching TunnelConnect profile. Connecting to a Mac instead? See the Mac screen sharing guide.


1. Turn on the VNC server

VNC servers listen on port 5900 by default. How you turn one on and set its password depends on the computer.

Raspberry Pi OS (RealVNC or wayvnc)

RealVNC Server is built into Raspberry Pi OS. To turn it on:

  1. Open Raspberry Pi Configuration (Menu → Preferences) and, on the Interfaces tab, set VNC to Enabled. Or run sudo raspi-config, choose Interface Options → VNC, and answer Yes.
  2. Reboot, or let the configuration tool restart the service. RealVNC Server then starts by itself on every boot and listens on port 5900.

To use a dedicated VNC password, open Menu → Preferences → VNC Server, then Options → Security, and under Authentication choose VNC password and set one. With the default setting (Unix users) you connect with the Pi's own user name and login password instead — see step 2.

For a Wayland session, wayvnc is the native VNC server. Its settings live in ~/.config/wayvnc.ini; set vnc_listen_address so it listens on the network rather than only localhost, then start it from your session.

Linux (x11vnc or TigerVNC)

TigerVNC — install the server package (sudo apt install tigervnc-standalone-server on Debian or Ubuntu, sudo dnf install tigervnc-server on Fedora). The first time you start it with tigervncserver, it asks for a VNC password. Sessions are numbered, and the port is 5900 plus the display number: :1 is port 5901. Give TunnelConnect the port, not the display number.

x11vnc — install it with sudo apt install x11vnc, set a password with x11vnc -storepasswd, then start the server:

x11vnc -rfbauth ~/.vnc/passwd -rfbport 5900 -display :0 -forever -shared

If the desktop refuses the connection because of X access control, add -auth guess.

Windows (TightVNC or UltraVNC)

TightVNC — install the server component. The first time it runs it asks for a VNC password; you can change it later in the TightVNC Server settings. It listens on port 5900.

UltraVNC — open UltraVNC Server, choose Properties → Authentication, and set a VNC password. The server listens on port 5900 by default. When Windows asks, allow TightVNC or UltraVNC through the firewall.


2. Set the VNC password


3. Check the port

TunnelConnect needs the server's port, which is 5900 for the first VNC display unless you changed it. Some servers number their displays: :0 is 5900, :1 is 5901, and so on.

From another computer on the same network you can confirm the port answers, for example nc -vz 192.168.1.20 5900. If nothing answers, the server's firewall is dropping the port.


4. Add the TunnelConnect profile

In TunnelConnect, add a profile:

FieldValue
Connection typeVNC server
Hostthe server's address — a LAN address such as 192.168.1.20, a hostname, or localhost inside a tunnel
Port5900, or the server's port from step 3
Passwordthe VNC password from step 2

TunnelConnect asks for the password when it connects and can store it in your macOS Keychain. The profile itself is stored in tunnelvnc.conf; the equivalent [[profile]] block is:

[[profile]]
id = "linux-box"
name = "Linux box"
host = "192.168.1.20"
port = 5900
security = ["vnc"]

Profiles that connect through a Cloudflare tunnel add a [profile.tunnel] block, as shown in the main guide.


5. None, SSH or Cloudflare tunnel?

The profile's connection type decides how TunnelConnect reaches the server.

None — a direct connection over the network. The right choice on your own LAN, where the VNC port is not exposed to the internet and you trust the network. No extra software is needed.

SSH — the VNC connection travels through an SSH connection to the same computer. The right choice when you have an SSH account on the server and do not want to expose its VNC port: everything the screen shows is encrypted by SSH.

Cloudflare tunnel — the connection goes through cloudflared and a Cloudflare Access TCP hostname. The right choice when there is no direct route: the server is behind carrier-grade NAT or a changing IP address, or you do not want to open any ports. Both sides only need outbound connections. You need cloudflared installed on the Mac running TunnelConnect, and a Cloudflare Access TCP hostname that forwards to the server's port 5900 — see the main guide for the profile settings.

If the connection fails, see If something is wrong in the main TunnelConnect guide.