Getting Started

Purpose

• Get the app running for the first time on a new machine.
• saved connect You the desktop app hosts.json encrypted at rest, on this machine Target server SSH / RDP / etc. MangoSSH never routes your traffic through a third-party server — every connection you save is stored locally (encrypted at rest by Personal Vault, on by default — see the next chapter), and every session goes straight from your machine to the target.

How to do it

1. 1Download and run the MangoSSH installer for your OS (Windows MSI/EXE, macOS DMG, or Linux AppImage/deb, depending on what's been built for your platform).
2. 2Launch MangoSSH.
   • On first launch it creates its local data directory (host list, keys, settings) under your OS's standard app-data location — nothing to configure manually.
3. 3The app opens on the Dashboard view (formerly "Sessions") — your list of saved connections, empty on a fresh install.

How to verify

1. 1Look at the toolbar across the very top of the window.
   • Expect to see, left to right: Dashboard , SSH , RDP , VNC , SFTP , a More dropdown, a Scripts dropdown, a Hosts toggle, and Settings at the far right.
2. 2If any of those is missing, or the whole window is white/blank with no toolbar at all, stop here and see the troubleshooting note below — don't proceed to the next use case on a broken launch.
3. 3Click Settings , then click About MangoSSH at the bottom of the left rail (the info-icon row, below Documentation and Report an issue).
   • Expect a modal titled "About MangoSSH" to open showing a version number — note it down, you'll want it later if you ever need to report a bug.
4. 4Click the × in the modal's top-right corner (or press Esc) to close it and return to Settings.

Troubleshooting

• Window opens but every page is blank — this has historically been caused by a front-end HTML/CSS regression after an update; restart the app once (a full quit, not just closing the window) and if it recurs, check for an update.
• App won't launch at all on Windows — right-click the executable → Properties → unblock, if Windows flagged the download as from an untrusted publisher (expected for a non-Store-signed build).
• macOS says the app is damaged / from an unidentified developer — right-click → Open the first time (bypasses Gatekeeper's quarantine flag for an unsigned/ad-hoc build).

Purpose

Understand the layout so every other use case in this guide makes sense — where the toolbar, sidebar, and the More/Scripts/Settings menus live.

How to do it

1. 1Top toolbar — protocol buttons (Dashboard, SSH, RDP, VNC, SFTP), a More dropdown (Terminal, Telnet, Serial, Cloud Browse, Cloud Mount, Cloud Sync, Wake-on-LAN, Zero Trust, Servers, Connection Dashboard, Tab Overview, Kubectl, Import sessions), a Scripts dropdown (Run Scripts, Monitor Script Runs), a Hosts toggle (sidebar vs. horizontal tab bar for connected sessions), and Settings .
2. 2Left sidebar (visible on the SSH/RDP/VNC views) — your saved connections, grouped, with a filter box at the top and a status dot per connection (green = connected).
3. 3Main pane — the active view: a connection list, an open terminal, an RDP/VNC canvas, or a Settings page.
4. 4Settings — its own two-column layout: a left rail of setting categories (Profiles, SSH Keys, Encrypted Vault, Cloud Sync, Team Vault, License, Audit Log, Appearance, Groups, Host visibility, Avatars, Connection, Debug, AI Assistant, Self Hosting Vault, Cloud Vault) and the selected category's page on the right.

How to verify

1. 1Click Dashboard .
   • Expect a grid/list of connection cards (empty if this is a fresh install) and no leftover sidebar from another view.
2. 2Click SSH .
   • Expect the left sidebar to appear (a filter box at top, "+ Add SSH Host" button, and any saved hosts grouped underneath) with an empty terminal pane on the right.
3. 3Click RDP , then VNC , then SFTP in turn.
   • Expect each one to swap the main pane's content completely — e.g. switching from SSH to RDP should not still show the SSH sidebar's host list underneath the RDP form.
4. 4Click the More dropdown.
   • Expect a menu listing (in order) Terminal, Telnet, Serial, Cloud Browse, Cloud Mount, Cloud Sync, Wake-ON-LAN, Zero Trust, Servers, Connection Dashboard, Tab Overview, Kubectl, and "Import sessions…" — count them; if any is missing, note which one before reporting it.
5. 5Click Settings .
   • Expect a two-column layout: a left rail with category buttons (Profiles, SSH Keys, Encrypted Vault, Cloud Sync, Team Vault, License, Audit Log, Appearance, Groups, Host visibility, Avatars, Connection, Debug, AI Assistant, Self Hosting Vault, Cloud Vault) and a blank/landing panel on the right until you click one.

Troubleshooting

• A toolbar button does nothing when clicked — check Settings → Debug for a verbose logging toggle, restart, and reproduce; if it's reproducible, it's worth reporting as a bug rather than a configuration issue.

Purpose

Save a reusable connection so you don't retype host/user/credentials every time.

How to do it

1. 1Click SSH in the toolbar, then + Add SSH Host .
2. 2Fill in a Name (a friendly label — this is what shows in the sidebar, not the hostname), the Host (IP or DNS name) and Port (22 by default), and a Username .
3. 3Pick an authentication method from the pill row (Password, Key only, Key + Password, Key + Interactive, MFA/Interactive, SSH Agent, PKCS#11, Windows Hello, or one of the external-secret-manager options: pass, Bitwarden, AWS SSM, Doppler, 1Password) — the full breakdown of every method is its own chapter.
4. 4Optionally assign a Group (for organizing the sidebar and, if configured, for inheriting a shared bastion/credential — see the Groups use case) and pick an Avatar icon.
5. 5Click Add host at the bottom of the modal.
   • This only saves the host and closes the modal — it does not connect by itself; connecting is a separate click on the new sidebar entry (next step).

How to verify

1. 1Immediately after clicking Add host , expect the modal to close and the new entry to appear in the left sidebar under the group you chose (or "Default" if you left it blank) — its status dot should be gray/idle, not yet green.
2. 2Click the new sidebar entry once.
   • Expect the status dot to change color while it connects, then turn green, and a terminal pane to open on the right with a live shell prompt from the remote host (e.g. user@hostname:~$ ).
3. 3Type whoami and press Enter.
   • Expect the output to match the username you configured (or whatever the server maps it to, e.g. for certificate-based principals).
4. 4Close the session (toolbar's disconnect icon, or the sidebar context menu's Disconnect ) and confirm the status dot returns to gray — this proves disconnect state is tracked correctly, not just that connect worked once.

Troubleshooting

• "Connection refused" — nothing is listening on that host/port; confirm the SSH daemon is running and the port/firewall is correct.
• "Connection timed out" — a network path or firewall issue, not an MangoSSH/auth issue; test with a raw TCP check from the same machine (e.g. Test-NetConnection host -Port 22 on Windows) before troubleshooting further inside the app.
• "Authentication failed" immediately — double-check the auth method actually matches what the server accepts (e.g. it's set to password auth but the server has PasswordAuthentication no ).
• Host key changed / trust prompt appears unexpectedly — see the Host Key Trust & TOFU use case in the SSH chapter before accepting a changed key blindly.

Purpose

Maintain your saved connection list as servers change — rename, re-point, clone for a similar host, or remove one that's gone.

How to do it

1. 1Edit : right-click a host in the sidebar → .
   • Edit , change any field, click the save button.
   • Changes only apply the next time you open a session on that host — an already-open session is never affected.
2. 2Duplicate : right-click → Duplicate .
   • The copy is created immediately (no confirmation dialog) with " (copy)" appended to its name — e.g. "prod-db1" becomes "prod-db1 (copy)".
   • Any saved password/passphrase is deliberately NOT carried over, even if the original had one saved.
3. 3Delete : right-click → 5 Delete .
   • A confirmation reads exactly: "Delete host \" < name > \"?
   • This can't be undone." — click the confirm button to proceed or Cancel to back out.
   • If the host is shared via Team Vault instead, a different 3-button dialog appears asking whether to delete your local copy only or also remove it from the Team Vault for everyone.

How to verify

1. 1Right-click a test host → Edit, change its Port to a deliberately wrong value (e.g. 2222), save, then click the host and confirm the connect attempt fails/times out at that wrong port — proving the edit actually took effect.
   • Edit it back to the correct port and confirm it connects normally again.
2. 2Right-click the same host → Duplicate.
   • Expect a new sidebar entry named " < original name > (copy)" to appear immediately, right below or near the original.
   • Open the copy in Edit and confirm the password field is empty even if the original has a saved password (check its "saved" indicator).
3. 3Right-click the copy → Delete.
   • Expect the exact confirmation text "Delete host \" < name > (copy)\"?
   • This can't be undone." Click confirm and immediately verify the entry disappears from the sidebar without needing to reopen the app.

Troubleshooting

• Deleted a host by mistake — there's no undo; if Cloud Sync or a vault backup is configured, a prior sync snapshot may still have it (check Settings → Cloud Sync / the relevant vault tier's history if available).
  • Otherwise it must be re-added by hand.

Purpose

• Keep entirely separate sets of hosts, keys, and settings — for example, a "Work" profile and a "Personal" profile, or one profile per client if you do contract IT work — without them ever mixing.
• Each profile gets its own data directory: its own hosts.json , keys, vault config, and settings.
• Switching profiles is a full context switch, not a filter — a host saved in one profile is invisible from another.

How to do it

1. 1Open Settings → Profiles.
2. 2Type a name into the "New profile name" field (e.g. "Client-A"), leave "Copy hosts & vault from the current profile into the new one" checked if you want a starting point (it's checked by default) or uncheck it to start completely empty, then click Create .
3. 3The new profile appears in the list, but you are NOT switched to it automatically — this is deliberate (an earlier version auto-switched and caused "I lost all my hosts" confusion when the new profile turned out empty).
   • Click Switch next to it yourself when you're ready.
4. 4Confirm the dialog that reads "Switch to profile ' < name > '? … Any open sessions will close." — clicking through it triggers an app restart to load the new profile's data.

How to verify

1. 1On Profile A, add a test host named something distinctive (e.g. "PROFILE-A-TEST").
2. 2Go to Settings → Profiles, click Switch next to Profile B, confirm the restart dialog, and wait for MangoSSH to relaunch.
3. 3Open the SSH view and confirm "PROFILE-A-TEST" is nowhere in the sidebar — not grayed out, not filtered, genuinely absent.
   • This is what proves real storage isolation rather than a display filter.
4. 4Go back to Settings → Profiles, Switch back to Profile A, confirm the restart, and confirm "PROFILE-A-TEST" reappears exactly as you left it.

Troubleshooting

• Added a host but it "disappeared" — almost always means you're now on a different profile than the one you added it under; check the active profile in Settings → Profiles before assuming data loss.