Guides · Connecting
VNC and Apple Remote Desktop
View and control Linux desktops, Macs and anything else that runs a VNC server, in a MangoSSH tab. For a Mac, sign in with the Mac's own account through Apple Remote Desktop authentication, which also wakes and unlocks that user's session.
- Built-in VNC client
- Windows · macOS · Linux
- About 5 minutes
Add a VNC host
Open Add Session → Add VNC host. Or click VNC on the main toolbar and then Add VNC Host.
Give it a Name and a Group, then the Host / IP and Port. The port defaults to 5900, which is display
:0. Display:1is usually 5901, and so on.Leave macOS username blank for Linux and Windows VNC servers. Enter the VNC password in Password.
Keep Save password in OS keystore ticked to store it in your operating system's keychain, or untick it to be asked each time.
Click Add & Connect.
The host appears in the sidebar; click it to connect later. If no password is saved, MangoSSH asks for one. If a connection fails, the page shows the error with Retry and Ping buttons, so you can tell a wrong password from a host that is not answering.
Add a Mac (Apple Remote Desktop)
macOS has no RDP server. Its Screen Sharing speaks VNC, with Apple's own sign-in method on top.
On the Mac, turn on Screen Sharing or Remote Management in the Sharing settings, and allow the account you will sign in with.
In MangoSSH, open Add Session → Add ARD Session. The same form opens as Add Apple Remote Desktop, and macOS username becomes required.
Enter the Mac's address, the macOS account name and that account's password, then click Add & Connect.
An Apple Remote Desktop host is an ordinary VNC host with a username. What matters is the username: whenever one is filled in and the Mac offers Apple's method, MangoSSH uses it.
A Mac often offers two ways in: the fixed password from VNC viewers may control screen with password, and per-account sign-in. The fixed password shows the screen as it is, which may be asleep, locked or black. Signing in with a macOS account wakes and unlocks that user's session.
How the sign-in method is chosen
The server lists the methods it accepts, and MangoSSH picks one in this order. The one used is shown in the session bar next to the screen size.
| Method | Picked when | What is encrypted |
|---|---|---|
| VeNCrypt (TLS) | The server offers it. Always preferred. | Everything. With a username and password it signs in with both, with only a password it uses the VNC password, with neither it uses TLS alone. |
| Apple Remote Desktop | You entered a macOS username and the server offers it. | The sign-in only. |
| VNC Authentication | You entered a password. | The sign-in only. |
| None | The server asks for no password. | Nothing. |
With VNC Authentication or Apple Remote Desktop, only the sign-in is protected. The picture and your keystrokes, including anything you type into the remote machine, cross the network in the clear. Over anything but a trusted LAN, prefer a server with VeNCrypt, or carry VNC inside an SSH tunnel: forward a local port to the server's 5900 (see Port forwarding) and connect to 127.0.0.1 on that port.
During a session
The session bar shows the host name, the remote screen size and the sign-in method in use, with two buttons:
- Fit re-fits the picture to the viewer, keeping its shape. You may see empty bars at the sides.
- Disconnect ends the session.
The picture always scales to fit the viewer and refits as you resize the window. If the remote side changes its resolution, the viewer follows. Click the screen to send it your keyboard and mouse. Several VNC sessions can be open at once, each in its own tab.
MangoSSH asks the server to draw the mouse pointer separately rather than into the picture. On macOS Screen Sharing in particular, that keeps pointer movement responsive.
Certificates
When a server uses VeNCrypt, the first connection shows Unknown server certificate with the certificate's SHA-256 fingerprint. Check it if you can, then click Yes, Trust & Connect. The certificate is pinned, and every later connection must present the same one. If it changes, the connection is refused with VNC host key mismatch and both fingerprints.
This version has no button to forget a pinned VNC certificate. If a server's certificate changed for a reason you know about, close MangoSSH, remove that server's entry from vnc_known_hosts.json in MangoSSH's data folder, and connect again.
Share a VNC host in a browser
You can give someone one VNC session in a plain browser tab, with nothing to install, through your relay.
Right-click the host and choose Set up browser access…. The wizard walks through the vault, the relay, the target and the link.
Afterwards, Share browser access… copies a new link.
For SSH and RDP, the relay signs in on the person's behalf and they never see a password. VNC is different: the relay only forwards bytes and the browser is the VNC client, so the person opening the link types the VNC password. Share the password separately, and only with people who may have it. See PAM Broker for tickets, approvals and revocation.
Limits in this version
- No clipboard. Copy and paste do not cross between your computer and the VNC session.
- Picture formats: Raw, CopyRect and ZRLE. Servers that insist on other encodings are refused with unsupported encoding.
- Sign-in methods: None, VNC Authentication, VeNCrypt (TLSNone, TLSVnc, TLSPlain) and Apple Remote Desktop. VeNCrypt's X.509 variants, Tight, UltraVNC and MS-Logon are not supported.
- No recording, pop-out or Ctrl+Alt+Del button for VNC sessions. Those are RDP features today; see Remote Desktop.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| “auth failed (bad password?)” | The password is wrong. For a Mac with a username filled in, it must be that macOS account's password, not the fixed VNC password. |
| A Mac shows a black or locked screen | You signed in with the fixed VNC password. Add the macOS username so MangoSSH uses Apple Remote Desktop sign-in. |
| “unsupported VNC security type” | The server only offers a method MangoSSH does not support. Enable VNC password or VeNCrypt TLS on the server. |
| “unsupported encoding” | The server does not fall back to Raw or ZRLE. Check its encoding settings. |
| “VNC host key mismatch” | The server's TLS certificate changed. See Certificates above. |
| Connection refused or timed out | No VNC server is listening on that port, or a firewall is in the way. Use Ping to see whether the host answers at all, and check the display number to port mapping (:1 is 5901). |
| Keys do nothing | The session does not have focus. Click the screen once. |