Vaults: Personal, Team and Cloud

The four vaults at a glance

Personal Vault is always on. The other three are opt-in, and a host is only ever sent to one of them if you add it there. Self Hosting Vault and Cloud Vault are the same system: the only difference is who runs the server.

All four are managed in Settings → Vault, which has one tab each: Encrypted Vault, Team Vault, Self Hosting Vault and Cloud Vault. The Encrypted Vault menu on the Dashboard is a shortcut to the same pages.

Personal Vault

MangoSSH encrypts your host list from the first save. By default the key is a random AES-256 key held in your operating system's keychain, so there is nothing to type and nothing to remember. The Encrypted Vault tab shows this as Encrypted (automatic), with a Vault View of every host and which shared vaults it is in.

This protects against someone copying your data files, a backup or a stray synced folder. It does not stop a program already running as your OS user, which can read the same keychain. If you want a password between that program and your hosts, add a master password.

Add a master password

1. Open Settings → Vault → Encrypted Vault and click Manage password protection….

2. Enter a New master password of at least 8 characters, confirm it, and click Add Password Protection.

3. Choose Auto-lock after inactivity: Never, 5, 15, 30 or 60 minutes without mouse or keyboard activity. The default is 15 minutes.

From then on MangoSSH starts on a MangoSSH is locked screen and asks for the password. The derived key is held in memory only and is cleared when the app closes or locks. The same dialog has Change Master Password… and Remove Password (Keep Automatic Encryption), which returns you to keychain-only encryption.

For a second factor, turn on Enable Two-Factor Unlock under Settings → Authentication. It asks for a code from an authenticator app at unlock, and gives you ten single-use recovery codes. It only applies when you use a master password.

Moving to another computer

Because the automatic key lives in this computer's keychain, copying MangoSSH's data folder to another machine is not enough. Use Settings → Cloud Sync instead. It carries your hosts, SSH keys, macros, scripts and saved passwords between your own devices through a shared folder or a URL (S3, WebDAV, R2), encrypted with a Sync Passphrase you enter on every device. With a shared folder, Sync automatically pushes on every change and checks for the other machine's changes about once a minute. With a URL you push and pull by hand. Cloud Sync is for one person's devices; use a shared vault for other people.

Admin or User: who can create a shared vault

Each device is set to User or Admin. Users can join a Team Vault or Self Hosting Vault that already exists. Only Admin devices can create a new one or recover one with a recovery code. A new install starts as User.

To switch, open Settings → Vault → Encrypted Vault → Account Type and click Admin. This setting only decides who can create a vault. Once you are inside one, what you can do is set by your role in that vault.

Team Vault

Team Vault needs no server. Every member points MangoSSH at the same shared folder, and whatever already syncs that folder (Syncthing, Dropbox, OneDrive, a mounted NFS share) moves the encrypted files between machines. A WebDAV or plain HTTP URL works too. Besides hosts, Team Vault carries shared scripts and a team audit log. The team audit log needs the shared-folder method.

You pick one of two sign-in modes when you set it up, and you cannot switch later without starting over:

• Team passphrase. Everyone types the same passphrase. Simple, but everyone has identical full access and there is no way to cut one person off.
• Device keypairs. Each device has its own key pair, kept in the OS keychain. An admin approves each new device, can make members admins, and decides per member whether they can edit the shared vault. New members are read-only until granted edit. Revoking a device re-encrypts the vault under a new key that the revoked device never receives. Creating the team shows a recovery code once; it restores admin control if every admin device is lost.

1. Open Settings → Vault → Team Vault.

2. Choose the Authentication mode and the Action: Create new team, Join existing team or Recover with a code.

3. Choose the Sync method and enter the shared folder or URL. Every member must use the same location. URL credentials are stored in the OS keychain.

4. Enter Your device label (teammates see it when they approve you) and, in passphrase mode, the Team passphrase. Click Set Up / Unlock.

To share a host, right-click it and choose Share with team, or use Sync → Share SSH Host with Team on the Dashboard. The host's saved password goes with it. Shared hosts appear in every member's host list with a team badge, and Copy makes your own editable local copy.

Self Hosting Vault and Cloud Vault

These use a vault server that stores only ciphertext and enforces who may read or write each record. Self-hosting the vault server walks through deploying one, creating the vault and adding teammates. Cloud Vault is the MangoSSH-hosted version: you sign in with your email and a six-digit code instead of entering a server URL, and it is a paid feature during the beta. A device connects to one Self Hosting Vault or Cloud Vault at a time.

Roles

An admin sets each member's role in the vault's Members tab.

The server enforces these roles. A change a role is not allowed to make is rejected and reported as a Not synced notice, while the rest of the sync still goes through.

Per-host restrictions

By default every member sees every shared host, within their role. An admin can click Restrict next to a host in the Hosts tab and pick which members may see it. The server then hides that host from everyone else, and admins still see it. Clearing every name removes the restriction.

Sync passwords

Off by default. With it off, saved passwords and key passphrases never leave the device's keychain, and teammates type their own. With it on, this device includes its saved credentials when it pushes its hosts, still end-to-end encrypted. It is a per-device choice and only affects the hosts this device pushes. For credentials people should use without ever seeing them, use the PAM Broker.

Shared hosts

Only hosts you add are sent to the server. In the Hosts tab, tick hosts in the grid and click Save & Sync. The grid only adds; it never removes a host that is already shared. The Synced via Self Hosting Vault list below it shows what is currently shared, with Unshare buttons. Unsharing stops this device updating the host. Deleting a host from your device deletes it from the vault too. A background sync runs about once a minute while the app is open.

Choose where a new host is stored

The Vault tab of the Add or Edit host form has a Choose Vault list. It is an action applied when you save, not a setting: it always starts on Personal Vault, and choosing another vault adds the host there in addition to your Personal Vault.

If the vault you pick is not set up on this device, MangoSSH tells you and keeps the host in Personal Vault only.

Troubleshooting