Pre-launch preview · purchasing opens soon

Documentation

Set up TunnelConnect

Setup guides

Choose the computer you connect to:

  • Connect to a VNC server — Raspberry Pi, Linux or Windows: enable the server, set a VNC password, then add the TunnelConnect profile.
  • Mac screen sharing — turn on Screen Sharing on the Mac, then add a TunnelConnect profile with the account's short name.

Screen sharing is not encrypted without a tunnel. For anything outside a network you fully trust, use an SSH or Cloudflare tunnel — the VNC server guide and Mac screen sharing guide say when.

1. Install TunnelConnect

TunnelConnect needs macOS 14 Sonoma or later, on Apple silicon or Intel.

Builds are ad-hoc signed for now, not notarised. The first time you open a downloaded copy, macOS will warn you. Right-click TunnelConnect in Finder and choose Open, or open System Settings → Privacy & Security and click Open Anyway. You only need to do this once per version.

TunnelConnect lives in the menu bar. It has no Dock icon until a viewer window is open.


2. Install cloudflared (only for tunnel profiles)

Profiles that connect through a Cloudflare tunnel need Cloudflare's cloudflared program. With Homebrew:

brew install cloudflared

TunnelConnect looks in /opt/homebrew/bin, /usr/local/bin, then your PATH. You can set cloudflared_path in the configuration file if it lives somewhere else. Profiles on your local network need nothing extra.


3. Your first profile

Click the TunnelConnect icon in the menu bar and choose Open Config. Profiles live in one readable file, tunnelvnc.conf, in TOML format. Each [[profile]] block is one computer, shown in the menu in the same order.

config_version = 1

[[profile]]
id = "pi5"                      # a-z, 0-9 and "-"; used for Keychain and logs
name = "Raspberry Pi 5"
port = 5900                     # VNC port on the far side of the tunnel
security = ["vencrypt", "vnc"]  # login methods to allow, in order

  [profile.tunnel]
  enabled = true
  hostname = "vnc.example.com"  # your Cloudflare Access TCP hostname
  local_port = 0                # 0 = pick a free port on this Mac

[[profile]]
id = "office-mac"
name = "Office Mac (LAN)"
host = "192.168.1.50"
port = 5900
security = ["vnc"]

Save the file. TunnelConnect reloads it by itself. A profile with a mistake is shown greyed out in the menu, and the others keep working.

Passwords never go in this file. A password key is an error. TunnelConnect asks for the password when you connect and can keep it in your macOS Keychain.


4. Connect

Click a profile in the menu. For a tunnel profile, TunnelConnect starts cloudflared access tcp on a free local port and waits until it is ready, usually in well under a second. It then connects and asks for the password if the server needs one. Tick Save in Keychain to skip the prompt next time.

Closing the viewer window stops that profile's tunnel. Quitting TunnelConnect stops all of them. Tunnels you started yourself are never touched.


5. In the viewer

ActionHow
Fit to window / actual sizeView menu
Full screen⌃⌘F
Disconnect⌘W
Quit TunnelConnect⌘Q

Every other key, including ⌘C and ⌘V, goes to the remote computer.


6. Activate your licence

TunnelConnect runs as a free 7-day trial from the first launch. The trial needs no internet connection.

After you buy, your licence key (TC1-XXXX-XXXX-XXXX-XXXX-XXXX) is shown on the success page and emailed to you. Paste it into Settings → Licence. A licence covers one Mac at a time. To move it, choose Deactivate on the old Mac first, then activate on the new one. If the old Mac is lost, contact support.

During the pre-launch preview, payments run in Stripe test mode, so no real licence can be bought yet. Your trial keeps working in the meantime, and it keeps working if the licence server cannot be reached.


7. The Keychain prompt

While builds are ad-hoc signed, macOS treats each new version as a different app. It may ask once whether TunnelConnect can use the passwords it saved earlier. Choose Always Allow.


If something is wrong

Cloudflare asks me to log in

Some Cloudflare Access hostnames need a browser login. cloudflared opens the login page in your browser, and TunnelConnect waits for it (up to login_timeout_secs, 120 seconds by default). Finish the login and the connection carries on.

"Port already in use"

Another program, often a cloudflared you started yourself, already uses that local port. Set local_port = 0 in the profile's [profile.tunnel] block so TunnelConnect picks a free one.

Nothing on my local network connects

On macOS 15 and later, open System Settings → Privacy & Security → Local Network and allow TunnelConnect.

"No supported login method"

The server only offers login methods TunnelConnect does not support yet. VNC password and VeNCrypt are supported today. RSA-AES (username and password) is planned for v0.2. To connect to a Mac through its Screen Sharing, see the Mac screen sharing guide.

Where are the logs?

Choose Open Log Folder in the menu, or open ~/Library/Logs/TunnelVNC/. Passwords and tokens are masked. You can attach a log to a support request.