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
| Action | How |
|---|---|
| Fit to window / actual size | View 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.