Guides · Connecting
SSH hosts, tab by tab
A reference for every tab of the Add / Edit SSH Host form: what each field and switch does, what it starts as, and when you would change it. Most hosts only ever need the General tab.
- Reference
- Windows · macOS · Linux
- 10 tabs
Open the form
- Add a host: click Add SSH Host in the host sidebar, or press Ctrl+N. The title reads Add SSH host and the cursor lands in Display name.
- Edit a host: right-click it in the sidebar and choose Edit. The title changes to Edit SSH host. Duplicate in the same menu copies a host, which is the quick way to add a near-identical one.
The tabs run down the left side of the form. You can switch between them freely; nothing is saved until you click the button in the footer.
| Tab | What it holds |
|---|---|
| General | Name, address, port, group, tags, username and password. |
| Authentication | How you prove who you are: identity, key, agent, FIDO2, passkey, PKCS#11, interactive, certificates. |
| Access | Persistent session on the relay, PAM Broker, Just-In-Time approval. |
| Proxy | Jump host (bastion), ProxyCommand, HTTP / SOCKS proxy. |
| Advanced | Protocol negotiation: compression, strict mode, algorithms, trusted host key. |
| Session | Terminal type, recording, data-copy controls, forwarding, reconnect, timeouts. |
| Vault | Which vault to add the host to when you save. |
| Environment | Tab colour and environment variables sent to the server. |
| Commands | Commands typed for you on connect and disconnect. |
| Notes | Free text about the host. |
General
The only tab you must fill in. Hostname / IP and Username are required; everything else has a working default.
| Field | What it does | Starts as |
|---|---|---|
| Display name | The name shown in the sidebar and on the session tab. Pick something you will recognise in a long list, such as web-prod-01. | Empty |
| Hostname / IP | The server's DNS name or IP address. The round button beside it fills the field from a MangoFly Private Network peer. | Empty (required) |
| Port | The SSH port on the server. | 22, or the default port in Settings → Connection |
| Group | One folder the host lives in. The button beside it opens Manage SSH Groups. See Groups and tags. | Default |
| Tags | Any number of labels. Press Enter or type a comma to add one, click its × to remove it. Use key:value, for example env:prod. | None |
| Username | The account you log in as. | The default username in Settings → Connection, if set |
| Password | The login password, used by password sign-in and by Key + Password. Leave it blank to be asked each time you connect. When editing, ***** means one is already stored; leaving the field blank keeps it. | Empty |
| Save password to OS keychain | On: the password goes to Windows Credential Manager, macOS Keychain or the Linux Secret Service, so you are not asked again and scripts can run. Off: it is discarded on save and you are prompted on every connect. | On for a new host |
| Add SSH Key, Certificate, or FIDO2 | A shortcut that jumps to the Authentication tab. | — |
| Stored in an external secret manager instead? | Fetches the password at connect time from pass, Bitwarden, AWS SSM, Doppler or 1Password through that tool's own command-line client. Picking one shows the field it needs (entry name, item ID, parameter, secret or secret reference). The CLI must be installed and signed in. | None — use the password above |
When you'd change the extras: use a secret manager when the password rotates or must never sit in a local keychain; leave the keychain switch off on a shared or borrowed machine.
Authentication
Leave this tab alone and the host signs in with the password from General. Open it to use anything stronger. The full walkthrough of each method is in Keys and sign-in methods; this is the map.
| Setting | What it does |
|---|---|
| Use an Identity | Sign in with a saved identity (a reusable username plus credential). While one is selected, the rest of this tab is hidden, because the identity supplies the credential. See Identities and groups. |
| How do you sign in? | Pick one: SSH Key, SSH Agent, FIDO2, Passkey, PKCS#11 or Interactive. Each shows only the fields it needs. |
| Which kind of key auth? | For SSH Key: Key Only, Key + Password, or Key + Interactive Login (a key plus a server prompt such as an OTP). |
| Private key file path | The key file. Relative paths start from your home folder. Browse… picks one. |
| Passphrase / Save passphrase | For an encrypted key. Saving puts it in the OS keychain; on by default for a new host. |
| SSH Certificate file / Revocation list — KRL | Present an OpenSSH user certificate with the key, and optionally refuse to connect if that certificate appears in a KRL. |
| Enterprise | Use this vault's certificate authority (short-lived certificates signed by your vault's CA) and HashiCorp Vault SSH. Both are covered in SSH certificates. |
| TOTP auto-fill | For Interactive and Key + Interactive: paste the Base32 secret from your authenticator setup and MangoSSH answers the "Verification code" prompt itself. |
Access
Settings that hand part of the connection to infrastructure beyond your own device: the relay, the PAM Broker, or an approver.
| Setting | What it does | Starts as |
|---|---|---|
| Keep this session alive on MangoSSH's relay | Connects through your relay server, which holds the SSH connection open. Close the app or switch devices, reopen the host, and you are reattached with recent scrollback replayed. Needs a relay configured in Settings → Relay Server; see Self-hosting the relay. | Off |
| PAM Broker | Shows whether the relay holds this host's credential and connects on members' behalf, with Set Up Browser Access… to configure it and Disable PAM Broker… to undo it. Details in PAM Broker. | Not set up |
| Prompt for Just-In-Time approval before connecting | Requires an active, time-boxed grant from your team vault before the connection starts. An admin approves the request first. Needs a Cloud or Self Hosting Vault. See Just-in-time access. | Off |
The PAM Broker block appears only when you edit a host that is already shared to a vault on which this device is an admin. A brand-new host has no vault record yet, so save it, share it, then edit it again. Persistent session and PAM Broker cannot both be on for one host.
Proxy
How the SSH connection reaches the server when it cannot go straight there. Use one of the three routes, not a combination: a ProxyCommand wins over an HTTP / SOCKS proxy, and either one wins over a jump host.
| Field | What it does | Starts as |
|---|---|---|
| Via SSH host | A saved SSH host to use as a bastion (ProxyJump). MangoSSH signs in to the bastion first, then opens the real connection inside it. If this is empty but the host's group has a default bastion, a line under the field says which one it inherits. | Direct connection (no bastion) |
| ProxyCommand | A command whose input and output become the SSH connection, like OpenSSH's ProxyCommand. Placeholders: %h host, %p port, %r remote user. | Empty |
| Quick preset | Fills ProxyCommand for AWS SSM Session Manager, GCP IAP, Cloudflare Access, Teleport (tsh), Tailscale or Azure Bastion. Edit the result to match your target. The provider's CLI must be on your PATH. | — |
| Type | An HTTP, SOCKS4 or SOCKS5 proxy, with Proxy Host, Proxy Port and an optional username and password (the password is stored in the OS keychain). SOCKS4 sends only the username. | None, or the proxy in Settings → Connection |
When you'd use this: servers in a private subnet behind a bastion, cloud instances with no public SSH port, or a corporate network that only lets traffic out through a proxy. Bastion chains and group inheritance are explained in Port forwarding and jump hosts.
Advanced
Protocol negotiation. The defaults work with nearly every server; change these only when a server needs something specific.
| Setting | What it does | Starts as |
|---|---|---|
| Enable compression | Compresses the SSH stream. Helps on slow links, costs CPU on fast ones. | From Settings → Connection |
| Strict mode | Modern algorithms only: no ssh-rsa, SHA-1 or CBC. Old appliances may then refuse to connect. | Off |
| Post-Quantum only (KEX) | Restricts key exchange to the ML-KEM hybrid. The connection only works if the server supports it too. | Off |
| Key exchange, Host key types, Ciphers, MAC algorithms | Tick boxes to allow only those algorithms in each category. A count shows how many you picked. Nothing ticked means "use the defaults". | Nothing ticked |
| Trusted host key (TOFU) | When editing, shows the fingerprint MangoSSH saved the first time you connected. Forget Host Key clears it so the next connection accepts whatever key the server presents. Use it only when you know the key changed legitimately, such as after a rebuild. | Shown when editing |
Session
How the session behaves once it is connected.
| Setting | What it does | Starts as |
|---|---|---|
| Terminal type (TERM) | The terminal type sent to the server. Change it only for appliances or old systems that draw a garbled screen, typically to xterm or vt100. | Default (xterm-256color) |
| Always record sessions | Records every session on this host even when recording is switched off globally in Session Logs. See Audit, recording and alerts. | Off |
| Follow server sshd log | Reads the server's own sshd log over the same session and adds its logins, failures and disconnects to your audit log. Linux and other POSIX servers only. | Off |
| Block file transfer (SFTP) on this host | Refuses the Files pane, drag-and-drop uploads and runbook file steps for this host. | Off |
| Block port forwarding on this host | Refuses local, remote and SOCKS forwards, including saved forwards and RDP tunnelled through this host. | Off |
| Enable X11 forwarding (-X) | Shows remote graphical programs on your screen. Needs a local X server. See X11 forwarding. | From Settings → Connection |
| Enable agent forwarding (-A) | Lets SSH commands you run on the server use the keys in your local ssh-agent. See Agent forwarding. | From Settings → Connection |
| Persistent shell (tmux) | Runs your shell inside a tmux session named after the host, so a dropped connection leaves your work running and reconnecting puts you back in it. Needs tmux and a POSIX shell on the server; a Windows server whose shell is cmd or PowerShell is skipped with a notice. | Off |
| Auto-reconnect on session drop | Retries automatically after a drop, waiting 1, 2, 4, 8, 16, then 30 seconds, up to 10 attempts. Silent when the password or passphrase is saved. | From Settings → Connection |
| Verbose / debug mode | Records each step of the connection (algorithms, route, host key, sign-in). View it with the Debug button on the session toolbar while connected. | On for a new host |
| Timeout (s) | How long to wait for the server to answer before giving up. | 15, or your Connection default |
| Keepalive (s) | How often to check an idle connection is still alive. | 15, or your Connection default |
| Server Alive Count Max | How many missed keepalives in a row before the connection counts as dead, like OpenSSH's ServerAliveCountMax. | 3, or your Connection default |
| Retries | Not currently applied to the connection. Use Auto-reconnect for automatic retries. | 0 |
The two Block switches stop MangoSSH from moving files or opening tunnels. Anyone who knows the host's password can still use another SSH client. For a boundary the user cannot step around, share the host through the PAM Broker, where the credential never reaches their device.
Vault
Choose Vault decides where the host is added when you save. It is an action, not a status: it starts at Personal Vault every time you open the form, including when you edit.
| Choice | What happens on save |
|---|---|
| Personal Vault | Nothing extra. Every host is already encrypted locally. |
| Team Vault | Shares the host with your whole team. There is no private-only mode. |
| Self Hosting Vault | Adds the host to your self-hosted vault, restricted to this device. Only a vault admin can do this. |
| Cloud Vault | Also syncs the host to Cloud Vault so it appears on your other devices. |
If the vault you pick is not connected on this device, the host is saved and stays in Personal Vault, and a message tells you so. See Vaults and Self-hosting the vault server.
Environment
| Setting | What it does | Starts as |
|---|---|---|
| Use a colour | Colours this host's terminal tab and sidebar row with the colour you pick in the swatch. Useful for marking production. | Off |
| Environment variables | Add Variable adds a KEY = value row; the bin icon removes one. Each is sent to the server just before the shell starts. | None |
The server decides which variables it accepts. OpenSSH only keeps names listed in AcceptEnv in sshd_config and silently drops the rest, so if a variable never shows up in the remote shell, that is the place to look.
Commands
| Field | What it does |
|---|---|
| Run command on connect | Typed into the terminal, followed by Enter, right after the shell connects. Example: tmux attach -t work || tmux new -s work. |
| Run command on disconnect | Typed into the terminal right before the session is closed. Example: tmux detach. |
A new host's connect command is pre-filled from the default command in Settings → Connection, if you set one.
Notes
Free text: what the host runs, who owns it, how to reach someone out of hours. Notes appear in the host row's tooltip and are matched by the sidebar search. They are not sent to the server and are not a place for secrets.
Save the host
- For a new host the footer button is Connect. It saves the host and connects straight away.
- When editing, it is Save changes. It saves without connecting.
- If something is missing, a red message appears above the footer: Hostname and username are required, Key file path is required for key sign-in, or the field a secret manager or PKCS#11 needs.
- Cancel, the × or Esc closes the form without saving.
If the OS keychain refuses to store a password (this can happen on an unsigned macOS build), MangoSSH says so. The password still works until you restart the app.
Groups and tags
A host has one group and any number of tags.
- Groups are folders in the sidebar. Create, delete and configure them in Manage SSH Groups, opened by the button next to the Group field or the ⚙ beside the sidebar's group filter. Each SSH group can have a Default bastion and a default Credential that its hosts inherit when they have none of their own. Deleting a group moves its hosts back to Default. More in Identities and groups.
- Tags are labels for slicing a fleet in more than one direction, for example
env:prodandregion:eu-weston the same host. A host saved before tags existed gets its group name as its first tag.
Both matter for Policies, which target all hosts, one group, or one tag. A tag must match exactly: a policy for eu does not apply to a host tagged eu:west.
Settings controlled by a policy
When a policy covers the host you are editing, the controls it governs show a badge under them and display the policy's value, not the host's own. These are the controls a policy can set:
- Access: Prompt for Just-In-Time approval before connecting
- Authentication: the Revocation list — KRL path
- Advanced: Strict mode
- Session: Always record sessions, Follow server sshd log, Block file transfer (SFTP) on this host, Block port forwarding on this host
| Badge | Meaning |
|---|---|
| 🔒 Set by policy Name (mandatory) | The control is locked. Only changing the policy changes it. |
| Set by policy Name · override for this host | The policy is a default. Click override for this host to unlock the control and use the host's own value. |
| Overriding policy Name · use policy value | This host has opted out. Click use policy value to follow the policy again. |
The top of the Session tab also lists Policies applied to this host, with a Manage policies link. A policy value is never written into the host itself: delete the policy and the host goes back to what it had. Badges appear only when editing an existing host.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| A switch is greyed out | A mandatory policy sets it. Look for the 🔒 badge under it. |
| No PAM Broker section on the Access tab | The host is new, not shared to a vault, or this device is not a vault admin. |
| The host connects through a bastion you never picked | Its group has a default bastion. The Proxy tab shows the inherited one; pick another bastion to override it. |
| An environment variable is missing on the server | The server's AcceptEnv does not list it. |
| Asked for the password on every connect | Save password to OS keychain is off, or the keychain refused the write. |
| The host key no longer matches after a server rebuild | Confirm the new fingerprint with the server's owner, then use Forget Host Key on the Advanced tab. |