Remote access by ID

How it works

The machine you want to reach is the host. With incoming access on, MangoSSH on the host connects out to your relay and registers. The relay hands back a Remote ID (9 digits) and a password (6 digits). The host never opens an inbound port.

The machine you connect from is the viewer. It also connects out to the relay and presents the ID and password. If they match, the relay pairs the two. MangoSSH then tries a direct peer-to-peer path between the machines. If that works, the relay only brokered the introduction. If not, the session keeps flowing through the relay.

Before you start

• A relay server. MangoSSH does not ship a public one. Run your own with the relay guide.
• The same relay on both machines. On the host and on every viewer, open Settings → Remote → Relay Server and enter the same Relay URL and Auth token. This is the same relay that SSH Persistent Sessions and the PAM Broker use. You set it once per device.

Two windows

Remote desktop has its own window, separate from your saved connections. Open it from Settings → Remote → P2P Remote Desktop → Launch P2P. It has two pages in its title bar:

• Dashboard shows this machine's Device ID and Access Password, a Connect to Remote card, who is connected to you, and your own open sessions.
• Settings holds the Access, Relay Server and Startup tabs. This guide calls it the Remote Access settings.

You can close the P2P window at any time. The machine stays reachable while the main MangoSSH app is running. Closing the main window keeps it running in the tray.

Allow incoming access

1. On the host, open the P2P window's Settings → Access.

2. Under How people can reach this machine, turn on Connect by ID — relay. Click Test beside it to check the relay answers.

3. The Connection details panel shows the Remote ID and Password with Copy buttons. Send both to the person connecting, the way you would send a password.

4. Choose what happens when someone connects (next section).

5. So the machine stays reachable after a reboot, open the Startup tab and tick Start MangoSSH on login. This covers a machine where someone signs in. For a Windows PC that must be reachable at the sign-in screen, use the unattended service.

Regenerate issues a new ID and password, which locks out anyone who had the old ones. The ID and password also change whenever MangoSSH restarts or re-registers with the relay. After five wrong passwords the relay refuses further attempts for that ID, and the host has to regenerate.

When someone connects

The When someone connects setting applies to every incoming connection on this machine. It also appears in the main window under Settings → Remote → Private Network. It is one setting, shown in two places.

RDP requests are asked about in the main window. MangoSSH Direct requests are asked about in the P2P window, which opens itself if needed.

RDP or MangoSSH Direct

The viewer picks how to see the host, per connection. The host serves whichever is asked for.

On macOS, grant the two permissions from the Remote Access settings: Grant… next to Screen Recording and Open Settings… next to Accessibility. Apple only lets you turn these on by hand in System Settings. It is a one-time step.

What each host platform supports

On Linux, release builds capture X11 and wlroots-based Wayland desktops such as Sway. GNOME and KDE on Wayland are not included, and pairing reports that. The Remote Access settings show which capture engine was detected. Linux hosting has not been tested on real hardware yet. Viewers work on every platform MangoSSH runs on.

Connect from another device

From the main window (RDP or MangoSSH Direct):

1. Open the RDP view and click Connect by ID.

2. Pick the Protocol: RDP (Windows Remote Desktop) or MangoSSH Direct (own capture + input, no RDP). Leave Connection method on Remote ID.

3. Enter the Remote ID and Password from the host.

4. For RDP, fill in Windows sign-in with an account on the host. The Remote ID and password only open the path. The Windows account signs you in. Tick Remember sign-in for this ID to keep the Windows credentials in your OS keychain. Display quality sets resolution and colour depth: lower is smoother on slow links.

5. Click Connect.

From the P2P window (MangoSSH Direct): on the Dashboard, fill in Remote Device ID and Access Password in the Connect to Remote card and click Connect.

In the Connect by ID dialog, Save this connection as a host adds the target to your sidebar for one-click reconnects. The saved password only works while the host keeps the same registration. After the host restarts, connect by ID again with the new values and save again.

Direct path and relay fallback

Every Connect by ID session tries a direct connection first and falls back to the relay by itself. There is nothing to switch on. A direct path is usually faster, and the session's data then never passes through the relay. Sessions are encrypted between the two machines on either path.

• A direct path needs a Windows host. macOS and Linux hosts always use the relay.
• To find a path through NAT, MangoSSH asks public STUN servers (Google and Cloudflare) for each machine's public address. In the Secure edition that lookup is off, so a direct path only forms between machines on the same network.
• Some networks block the direct path, for example strict corporate firewalls. The relay fallback covers them, at relay speed.

Unattended access on Windows

The in-app agent only runs while someone is signed in to Windows and MangoSSH is running. To reach a PC that sits at the sign-in screen, for example after a Windows Update reboot, install the MangoSSH Windows service. It starts at boot, before anyone signs in. This is Windows only.

1. Save the relay on the Relay Server tab, and set When someone connects to Let them straight in — ID and password only. Nobody can click Allow before Windows sign-in, so the service only runs in password mode.

2. Turn on Remote Desktop in Windows on this PC. The service reaches the sign-in screen through it.

3. On the Startup tab, under Unattended access before Windows login, click Install Service and approve the Windows administrator prompt.

4. When the status reads Installed and running, the service's own Remote ID and Password appear. Write them down. Unlike the in-app agent's, they stay the same across restarts, reboots and reinstalls. Only Uninstall Service resets them.

Connect to it with Connect by ID and the RDP protocol, then sign in with a Windows account. MangoSSH Direct can also reach the service, but its capture before sign-in is still experimental. If someone is connected, Disconnect them ends their session.

The service copies the relay URL, the token and the allow-list below when it is installed. After changing any of them, uninstall and install again. The service writes a log to C:\ProgramData\MangoSSH\service.log.

Also reachable through this PC

A registered agent can pass connections on to other machines on its own network, but only to the ones you list. The Also reachable through this PC box, on the Startup tab on Windows, takes one host:port per line:

127.0.0.1:22
10.0.0.5:3389
10.0.0.12:5900

Click Save list. The agent may reach only these targets, plus this PC's own RDP. The list is used in two places:

• Browser sharing (next section). Picking another RDP host there adds it to the list for you.
• PAM Broker targets behind NAT. In the Browser Access wizard's target step, Reach it through a host agent (target behind NAT) sends a brokered SSH, RDP or VNC session through this agent instead of having the relay dial the target. That needs the Windows service (for its stable ID), password mode, and the target on this list. An agent serves one session at a time. See PAM Broker.

The running app applies a saved list at once. The service reads it only at install.

Share in a browser

You can hand someone a link that opens an RDP desktop in any web browser, with nothing to install. The browser reaches the desktop through your relay and this PC, so RDP is never exposed to the internet.

1. In the Remote Access settings, click Share an RDP host in a browser.

2. Pick This PC to share your own desktop (Windows with Remote Desktop on), or a saved RDP host that this PC can reach. MangoSSH turns on incoming access if needed, adds the host to the allow-list, and copies the link.

3. Send the link. The person opens it and signs in with that machine's Windows account.

Troubleshooting