Relay-Backed Access & Fleet Oversight

Purpose

• MangoSSH's relay-backed features (SSH Persistent Sessions, PAM Broker for SSH/RDP/VNC, and Connect by ID) all ride the same relay-server deployment — one process, one URL, exposing a different route per feature.
• This page is where you point MangoSSH at it once.

How to do it

1. 1Go to Settings → Remote → Relay Server (this page used to be called "Persistent Sessions" — same page, renamed to reflect that it configures more than one feature).
2. 2Enter the Relay URL (e.g. wss://relay.example.com or ws://192.168.x.x:8878 for a plain self-hosted instance with no TLS yet) and, if your relay was started with RELAY_AUTH_TOKEN set, the matching Auth Token.
3. 3Click Save.
   • This immediately attempts to register Connect by ID against the same relay — you don't need to separately configure anything under Remote Access for that to start working.
4. 4If you're self-hosting relay-server yourself, see the relay-server/README.md in the MangoSSH repository for how to deploy it (a Docker Compose file is provided) — deploying the relay itself is outside MangoSSH the app.

How to verify

1. 1After Save, the page should show no error next to the Save button.
   • Open Settings → Remote → Remote Access → Access tab and confirm an ID and password have appeared automatically under "Connect by ID" — that's the confirmation the relay is actually reachable, not just that the URL field accepted text.
2. 2On an SSH host with "Keep this session alive on MangoSSH's relay" ticked (Edit host → Access tab), connect, then close and reopen MangoSSH — the terminal should still be there with its scrollback intact.

Troubleshooting

• Connect by ID never generates an ID/password after saving — confirm the URL is actually reachable (curl/browser to http(s):// < host > : < port > /healthz should return "ok") — an unreachable relay fails this step silently rather than showing an error here.
• "No relay server is configured" when trying PAM Broker or Persistent Sessions — this page's URL field is empty or was never saved — fill it in and click Save.
• Works for SSH but a colleague's RDP PAM Broker still won't connect — each device configures its own copy of this URL locally — it isn't synced between devices or team members.
  • Every device that uses any relay-backed feature needs this page filled in itself.

Purpose

• Keeps an SSH terminal alive on the relay server even after you close MangoSSH entirely, so you can reopen the app — or a different device — later and pick the session back up with its scrollback intact.
• The relay genuinely holds your real SSH credential server-side while a persistent session is open — that's what makes reattach-from-anywhere possible.
• Only use this against a relay you trust (your own, or your organization's).

How to do it

1. 1Configure a relay under Settings → Remote → Relay Server first (see the previous use case).
2. 2Edit the SSH host you want this for, open the Access tab, and tick "Keep this session alive on MangoSSH's relay."
3. 3Connect normally.
   • MangoSSH connects through the relay instead of directly — the terminal behaves identically, but the relay is now the one holding the live SSH connection.

How to verify

• Connect, type something distinctive into the shell (e.g. echo hello-relay-test), then fully quit MangoSSH (not just disconnect).
• Reopen MangoSSH and reconnect to the same host — expect the terminal to reattach with echo hello-relay-test and its output still visible in the scrollback, rather than opening a brand-new blank shell.

Troubleshooting

• Reconnecting opens a fresh shell instead of reattaching — confirm "Keep this session alive on MangoSSH's relay" is actually ticked on this host — without it, MangoSSH connects directly and there's nothing on the relay to reattach to.
• "No relay server configured" on connect — set one up on the Relay Server settings page first.

Purpose

• Lets someone connect to a host — through a normal browser tab, no MangoSSH install needed — without ever seeing its password.
• An admin provisions the credential onto the relay once; everyone else's link just works.

How to do it

1. 1Configure a relay under Settings → Remote → Relay Server.
2. 2On the host you want to broker, open Edit → Access tab (SSH) and click "Set up browser access…" — this opens the Setup Browser Access wizard.
3. 3Vault tab: confirm this host is shared through a Self Hosting Vault or Cloud Vault (PAM Broker needs one, since that's what lets other vault members discover the host).
4. 4Relay tab: confirm/Test the relay URL (pre-filled from step 1).
5. 5Target tab: confirm the host/port/username/password the relay should use to reach the target, then "1 · Check host key" followed by "2 · Provision" — the relay connects once, seals the credential, and never needs the plaintext password again after this.
6. 6Share tab: click "Copy link — valid 1 hour" and send it to whoever needs one-time access.

How to verify

1. 1After provisioning, open the copied link in a plain browser tab (not MangoSSH) on a different machine — expect a live terminal (SSH) or a rendered desktop (RDP/VNC) with no password prompt.
2. 2Ask the person you shared the link with whether they ever saw a password — they shouldn't have; the relay authenticated on their behalf.
3. 3In MangoSSH, Edit → Access tab → "Disable PAM Broker…" removes the credential from the relay; confirm a previously-working link now fails.

Troubleshooting

• "Check host key" fails with a connection error — the address you entered is what the RELAY needs to reach the target, which is not always the same address you personally use — e.g. if the relay runs in Docker or on a different network segment.
  • Use the address reachable FROM the relay.
• Wizard opens on the wrong protocol's fields — the wizard reads the host's own saved protocol (SSH/RDP/VNC) automatically — open it from the specific host record you mean to broker, not a generic entry point.
• VNC target has no password field at all — for VNC the relay only ever forwards bytes rather than acting as the client, so it has no credential to hide — whoever you share a VNC link with still needs the real VNC password, sent to them separately.

Purpose

The fast path once a host is already PAM-broker-provisioned — mint a new time-boxed link without reopening the full wizard.

How to do it

1. 1Right-click a PAM-brokered host in the sidebar and choose "Copy browser link," or reopen "Setup Browser Access" and use its Share tab directly.
2. 2Send the copied link to whoever needs access.

How to verify

Confirm the link opens a working session in a plain browser with no MangoSSH install and no password prompt, and stops working after the stated expiry (default: 1 hour).

Troubleshooting

• Right-click has no "Copy browser link" option — the host isn't PAM-broker-provisioned yet — run "Setup Browser Access" first.

Purpose

Reach a machine by a short ID and one-time password instead of its IP address — useful for machines behind NAT or without any port forwarding set up, the same idea as RustDesk/TeamViewer's "Your ID."

How to do it

1. 1On the machine you want to be able to reach (the host side), configure a relay under Settings → Remote → Relay Server, then check Settings → Remote → Remote Access → Access — an ID and password appear automatically once the relay is reachable, no separate toggle needed.
2. 2On the connecting device, open Connect by ID (the RDP toolbar, or the + button), choose the "MangoSSH Direct" or "RDP" protocol as appropriate, and enter the target's ID and password.
3. 3Click Connect.
   • MangoSSH first tries a direct P2P path (faster, and the relay operator never sees the session) and falls back to relaying through the server automatically if P2P doesn't succeed.

How to verify

1. 1On the host machine, Settings → Remote → Remote Access → Access should show a live grouped ID (e.g. 123 456 789) and a password with Copy buttons — that confirms it registered with the relay successfully.
2. 2From a second machine, connect using that ID/password and confirm a real session opens; check the connection's own status/debug view for whether it actually went P2P or fell back to the relay.

Troubleshooting

• No ID/password ever appears on the host — confirm Settings → Remote → Relay Server has a working URL saved — Connect by ID depends on that same relay being reachable.
• ID/password appear but a remote connect fails immediately — confirm the host's Backend choice (Remote Access → Backend tab: "This PC's RDP server" vs. "MangoSSH Direct") matches what the connecting side is trying to reach — picking the wrong one on the connect side fails right after authentication succeeds, which reads as a generic "connection failed" rather than an obvious protocol mismatch.

Purpose

MangoSSH's own screen-capture-and-input pipeline, for reaching machines that don't have Windows RDP enabled (or that you'd rather not expose RDP on at all) — an alternative backend, not a replacement for RDP.

How to do it

1. 1On the target (host) machine: Settings → Remote → Remote Access → Backend tab, select "MangoSSH Direct" instead of "This PC's RDP server."
2. 2Confirm the ID/password under the Access tab are populated (see the Connect by ID use case above).
3. 3From the connecting device, use Connect by ID and pick MangoSSH Direct as the protocol.

How to verify

Connect and confirm you see the target's real desktop and can move the mouse/type — this is a genuinely different capture pipeline from RDP, so test both mouse movement and keyboard input explicitly rather than assuming RDP's own behavior carries over.

Troubleshooting

• Connects but the screen never updates — confirm the target machine is Windows and currently logged in — MangoSSH Direct captures the interactive desktop session and has no way to reach a locked/logged-out machine (this is a known, current limitation, not a bug).
• "MangoSSH Direct" isn't listed as a Backend option — this feature is Windows-host-only today — it isn't available to select on a non-Windows target.

Purpose

The settings page that controls whether, and how, THIS machine can be reached by someone else — the host side of both PAM Broker and Connect by ID.

How to do it

1. 1Settings → Remote → Remote Access, Backend tab: choose what an incoming connection actually reaches — this PC's real RDP server, or MangoSSH Direct's own capture pipeline.
2. 2Access tab: view this machine's Connect-by-ID identity (ID + password, regenerable), and see every way this machine can currently be reached (Classic RDP / Connect by ID relay / Direct IP Access), each with its own on/off toggle.
3. 3Startup tab: optionally install this as a background Windows service so it's reachable even when no one is logged into the app itself (Windows-only).

How to verify

1. 1Toggle Connect by ID off, confirm a previously-working remote connect from another device now fails cleanly; toggle it back on and confirm it works again.
2. 2Regenerate the password (Access tab) and confirm the OLD password no longer works for a new connect attempt.

Troubleshooting

• Regenerating the password doesn't seem to do anything — an already-open session isn't affected by a password regeneration — it only changes what's needed to START a new connection.

Purpose

Joins this machine to a MangoFly WireGuard overlay so it gets a stable 100.x.x.x address reachable from anywhere — useful when a target's real IP changes (DHCP) or isn't directly reachable at all.

How to do it

1. 1Settings → Remote → Private Network.
2. 2Enroll this device against your MangoFly coordination server (see MangoFly's own setup if you haven't deployed one yet — this is separate infrastructure from MangoSSH's own relay-server).
3. 3Once enrolled, peers the coordination server knows about appear in the left list; click one to send its overlay IP straight into the "Connect by address" panel on the right.

How to verify

1. 1Confirm this device's own overlay IP is shown and pings successfully from a peer also on the overlay.
2. 2Pick a peer from the list, confirm its IP auto-fills the Connect panel, and that an RDP connection to that address succeeds even if the peer's real LAN IP has since changed.

Troubleshooting

• No peers ever show up — confirm the coordination server is actually reachable and this device finished enrolling — check the page's own status area for an enrollment error.
• This is permanent, not a one-off tunnel — joining an overlay is a standing network membership, not a per-connection tunnel — leave the overlay explicitly if you no longer want this machine reachable that way.

Purpose

A single screen for an admin to see and act on everything privileged-access-related across the fleet: who's connected right now, what's been recorded, and what's pending approval — reached from its own place in the sidebar (hideSidebar), not folded into ordinary Settings.

How to do it

1. 1Open PAM Dashboard from its own navigation entry (not under Settings).
2. 2Active Sessions: see every live session across every protocol MangoSSH tracks, with a Terminate action per row.
3. 3Relay-observed: sessions the relay itself can see (PAM-broker connections specifically) — a second, independent signal from Active Sessions, since a relay-brokered session isn't necessarily visible to this device's own local session list.
4. 4RDP recordings: browse and download server-enforced RDP session recordings (see "Record every session brokered through this host" in the PAM Broker Target tab).
5. 5Rotation / Strength / Unused / Shared / Audit / Roster faces: password rotation status, weak/stale credential flags, shared-but-unused hosts, and the vault's own member roster and audit trail.

How to verify

1. 1Open a live session from another device, confirm it appears in Active Sessions within the dashboard's normal refresh interval, and that clicking Terminate there actually ends it.
2. 2For a host with RDP recording enabled, connect, do something on screen, disconnect, and confirm a new recording appears under RDP recordings shortly after.

Troubleshooting

• A session I know is live doesn't show under Active Sessions — confirm you're looking at the right tier — relay-brokered sessions specifically surface under Relay-observed, not Active Sessions, since the two are independent signals with no shared source of truth.
• RDP recordings tab is empty even though recording is on — recording is enforced by the relay for PAM-broker sessions specifically — a direct (non-brokered) RDP connection is never recorded by this feature.

Purpose

Requires a live, time-boxed approval before a specific connection is allowed to proceed — for hosts sensitive enough that standing access, even vault-shared access, isn't enough on its own.

How to do it

1. 1Edit the host, Access tab, tick the Just-In-Time access requirement.
2. 2When a member without standing approval tries to connect, MangoSSH sends an approval request instead of connecting immediately.
3. 3An admin approves or denies the request from PAM Dashboard (or wherever pending JIT requests surface for that vault) — approval is time-boxed, not permanent.

How to verify

1. 1As a non-admin member, attempt to connect to a JIT-gated host and confirm you're blocked with a pending-approval message rather than connecting immediately.
2. 2As the admin, approve the request and confirm the requester's connection now proceeds; wait past the approval's time window and confirm a new attempt needs a fresh approval.

Troubleshooting

• Approval never seems to expire — check the configured approval duration for this vault/host — JIT approvals are intentionally time-boxed, so a very long duration can look indistinguishable from standing access.
  • Corrections to Existing Use Cases The Add SSH Host modal was reorganized this update.
  • The use cases on pages 13–24 and a few cross-references elsewhere were written against the older layout and now point at the wrong tab in a few places.
  • Nothing about what these features DO changed — only where their controls live.
  • Corrected here rather than by silently editing the original pages, so it's clear exactly what moved and why.
  • The Authentication tab is now a two-step picker
  • Affects: Choosing an Authentication Method; Password & Key-Based Authentication; MFA / Keyboard-Interactive Authentication; SSH Agent Authentication; Hardware-Backed Authentication — PKCS#11 & Windows Hello; External Secret-Manager Authentication
  • What changed The Authentication tab used to be one flat row of 13 pills.
  • It's now a two-step picker: Step 1 picks a family — Password, SSH key, SSH agent, Hardware-backed, or Interactive login — and Step 2 shows only that family's own fields.
  • The old "Key only / Key + Password / Key + Interactive" pills are now a 3-way sub-choice under the SSH key family.
  • "PKCS#11 / Windows Hello" are now a 2-way sub-choice under Hardware-backed.
  • The pass/Bitwarden/AWS SSM/Doppler/1Password external-secret-manager methods are no longer top-level pills at all — they're reached by expanding "Stored in an external manager instead?" under the Password family.
  • Editing an existing host still pre-selects the right family and sub-choice automatically from what's already saved.
• Read it as:
• Wherever the text says "pick the Password pill" — read it as "pick the Password family (Step 1), which shows the password field directly — no Step 2 needed" instead.
• Wherever the text says "pick the Key only / Key + Password / Key + Interactive pill" — read it as "pick the SSH key family (Step 1), then the matching sub-choice (Step 2)" instead.
• Wherever the text says "pick the SSH Agent pill" — read it as "pick the SSH agent family (Step 1) — single-method family, nothing to pick in Step 2" instead.
• Wherever the text says "pick the MFA (Interactive) pill" — read it as "pick the Interactive login family (Step 1) — single-method family, nothing to pick in Step 2" instead.
• Wherever the text says "pick the PKCS#11 / Windows Hello pill" — read it as "pick the Hardware-backed family (Step 1), then the matching sub-choice (Step 2)" instead.
• Wherever the text says "pick the pass/Bitwarden/AWS SSM/Doppler/1Password pill" — read it as "pick the Password family (Step 1), expand "Stored in an external manager instead?", then pick the manager (a chip, not a top-level pill)" instead.
• Wherever the text says "the Add/Edit SSH Host modal's Authentication tab has 13 pills" — read it as "the Authentication tab is a 5-family, two-step picker (13 underlying methods are still all reachable, just grouped)" instead.
  • HashiCorp Vault SSH now lives inside the Authentication tab
  • Affects: HashiCorp Vault SSH (CA-Signed Certificates)
  • What changed Previously stated as "configured on the Delegate tab, not the Authentication pill row." That's now backwards — it's a collapsible section inside the Authentication tab's SSH key family (collapsed by default; auto-expands if this host already has it configured).
  • There is no separate Delegate/Access-tab location for it.
• Read it as:
• Wherever the text says "Certificate-based delegate: HashiCorp Vault SSH, configured on the Delegate tab, not the Authentication pill row" — read it as "HashiCorp Vault SSH is configured inside the Authentication tab itself — pick the SSH key family, then expand the HashiCorp Vault SSH disclosure" instead.
  • "Delegate" is now "Access," and holds less
  • Affects: Every use case that says "Delegate tab" for Persistent Sessions relay, PAM Broker, or JIT
  • What changed The tab itself is renamed Access (same place in the nav rail).
  • Its scope narrowed at the same time: it now holds only the Persistent Sessions relay checkbox, the PAM Broker section, and Just-In-Time access.
  • Session recording, server-side audit, debug mode, and forwarding moved to a brand-new Session tab — see the next correction below.
• Read it as:
• Wherever the text says "Delegate tab" — read it as "Access tab — but only for Persistent Sessions relay / PAM Broker / JIT specifically; see below for anything else" instead.
  • Session recording, sshd-log following, debug mode, and forwarding moved to a new "Session" tab
  • Affects: Session Recording, Server-Side Audit & Debug Mode; Forwarding & Algorithm Policy; The Tamper-Evident Audit Log (its "Follow server sshd log" cross-reference)
  • What changed These six fields — Always record sessions, Follow server sshd log, Verbose/debug mode, X11 forwarding, Agent forwarding, and Auto-reconnect on session drop — all moved out of Delegate/Access into their own new Session tab, specifically to de-clutter what had become a very dense Delegate tab.
  • Strict mode and manual KEX/host-key/cipher/MAC selection did NOT move — they're still exactly where the original text says, on the Advanced tab.
• Read it as:
• Wherever the text says "Always record sessions (Delegate tab)" — read it as "Always record sessions (Session tab)" instead.
• Wherever the text says "Follow server sshd log (Delegate tab, POSIX targets only)" — read it as "Follow server sshd log (Session tab, POSIX targets only)" instead.
• Wherever the text says "Verbose / debug mode (Delegate tab)" — read it as "Verbose / debug mode (Session tab)" instead.
• Wherever the text says "X11 forwarding (Delegate tab)" — read it as "X11 forwarding (Session tab)" instead.
• Wherever the text says "Agent forwarding (Delegate tab)" — read it as "Agent forwarding (Session tab)" instead.
• Wherever the text says "Auto-reconnect on session drop (Delegate tab)" — read it as "Auto-reconnect on session drop (Session tab)" instead.
• Wherever the text says "Strict mode (Advanced tab)" — read it as "unchanged — still Advanced tab" instead.
• Wherever the text says "Manual KEX / host-key / cipher / MAC selection (Advanced tab)" — read it as "unchanged — still Advanced tab" instead.
  • Bastion ("Via SSH host") and ProxyCommand live on their own "Proxy" tab
  • Affects: Reaching a Target Through a Bastion or Zero-Trust Broker; Groups & Inherited Credentials (its "Via SSH host" verification steps); Zero Trust Broker Tunnels (Dedicated Panel) (its " → Use in SSH host" step)
  • What changed This one predates this session's changes — it was already wrong in the original text, not something this update broke.
  • "Via SSH host" (Proxy Jump) and ProxyCommand (including the Zero Trust quick presets — AWS SSM, GCP IAP, Cloudflare Access, Teleport, Tailscale, Azure Bastion) have always lived together on their own Proxy tab, confirmed directly against the current modal — never on Delegate/Access.
• Read it as:
• Wherever the text says "Via SSH host to another already-saved bastion host on the target host's Delegate tab" — read it as "Via SSH host on the target host's Proxy tab" instead.
• Wherever the text says "pick a saved bastion host from the "Via SSH host" dropdown on the Delegate tab" — read it as "pick a saved bastion host from the "Via SSH host" dropdown on the Proxy tab" instead.
• Wherever the text says "its own "Via SSH host" field on the Delegate tab" — read it as "its own "Via SSH host" field on the Proxy tab" instead.
• Wherever the text says "push the working command straight into a saved SSH host's Delegate tab" — read it as "push the working command straight into a saved SSH host's Proxy tab" instead.
• Wherever the text says "Use in SSH host to copy the resulting command into the Delegate tab" — read it as "Use in SSH host to copy the resulting command into the Proxy tab" instead.
• Wherever the text says "jump to) an SSH host's Delegate tab with the resulting ProxyCommand" — read it as "jump to) an SSH host's Proxy tab with the resulting ProxyCommand" instead.
  • The Audit Log gained a Console view
  • Affects: The Tamper-Evident Audit Log
  • What changed Not a correction so much as an addition: the audit log modal now has a Cards/Console toggle (icon buttons in the modal's title row).
  • Console shows the same entries as plain, colored, individually selectable text — useful for copying several log lines at once (e.g. into a ticket or an incident report), which the original Cards view doesn't support.
• Read it as:
• Wherever the text says "(no prior mention)" — read it as "a Cards/Console toggle now sits in the Audit Log modal's title row — Console is a plain-text, multi-select-and-copy view of the same entries" instead.