Self-hosting the vault server

How it works

Each device encrypts a host before sending it (AES-256-GCM, with a vault key that only member devices hold). The server stores the ciphertext, hands out new versions to other members, and enforces who may read or write each record. It is a sync service and an access-control service, never a decryption service.

There are no accounts and no passwords on the server. Every MangoSSH device has its own Ed25519 key pair, kept in the operating system's keychain, and signs every request with it. The server only ever learns the public half.

What you need

• A Linux x86-64 machine that runs Docker. A small VPS is plenty for a team (a Hetzner CX22 or similar, about €4–5 a month). A NAS or a spare always-on machine also works, if devices can reach it.
• A domain name pointing at the machine, if devices will sync over the internet. Caddy uses it to get a free Let's Encrypt certificate.
• Ports 80 and 443 open for the certificate and for HTTPS. Port 8787 stays private behind the proxy.
• MangoSSH on each device that will join.

Step 1 — Install the server

Download the vault server bundle onto the machine and run its installer. The bundle holds a pre-built image, so nothing is compiled on your server.

1. Install Docker and the Compose plugin, if the machine doesn't have them.

   curl -fsSL https://get.docker.com | sh

2. Point DNS at the machine. Create an A record, for example vault.yourteam.example, and wait until it resolves (dig vault.yourteam.example). The certificate can only be issued once it does.

3. Download the bundle.

   curl -fLO https://downloads.mangossh.com/mangossh/latest/mangossh-server-linux-x64.tar.gz

4. Check the download (optional). Print its SHA-256 and compare it with the vault server line in SHA256SUMS-selfhost, linked under Self-host the servers in the downloads section. That list names the versioned file, such as mangossh-server-1.0.99-linux-x64.tar.gz; it is the same file, so only the hash has to match. sha256sum -c would look for the versioned name and report it missing.

   sha256sum mangossh-server-linux-x64.tar.gz

5. Unpack and install.

   tar -xzf mangossh-server-linux-x64.tar.gz
   cd mangossh-server-*-linux-x64
   sudo ./install.sh --domain vault.yourteam.example

The installer puts the server in /opt/mangossh/vault/ and writes its .env with a random database password and the keys for the optional features. It starts a Caddy proxy that gets and renews the Let's Encrypt certificate, keeps port 8787 private to the machine, and prints the Server URL to enter in MangoSSH.

Step 2 — Create the vault from MangoSSH

1. Make this device an Admin. MangoSSH asks whether you are a User or an Admin the first time it opens, and only Admin devices can create a vault. If you chose User then, switch it here: open Settings → Vault → Encrypted Vault → Account Type and choose Admin.

2. Open the Self Hosting Vault tab in the same Vault group.

3. Under Create a new Self Hosting Vault, enter the Server URL (https://vault.yourteam.example), a Vault label such as your company name, and this device's label so teammates can tell devices apart.

4. Click Create Self Hosting Vault. This device becomes the vault's first admin.

5. Save the recovery code. It is shown once. It is the only way to regain admin control if every admin device is lost. Store it in a password manager or a safe, then click I've saved it.

Step 3 — Choose what to share

Creating a vault shares nothing by itself. Only hosts you add are ever sent to the server. Everything else stays on the device.

• To share hosts, open the Hosts tab of the vault page, tick them in the grid and click Save & Sync. The list below the grid shows what is shared, with an Unshare button per host. Shared hosts show a ☁️ Shared badge in your host list.
• Sync passwords decides whether saved passwords and key passphrases travel with shared hosts. Off, teammates get the host but type their own credential. On, the credential is included, still end-to-end encrypted.
• For credentials people should use but never see, share the host through the PAM Broker instead.

Step 4 — Add teammates

1. Send each teammate the Server URL and the Vault ID, shown in the vault pane with a copy button.

2. On their device they open Settings → Vault → Self Hosting Vault, fill in Join an existing Self Hosting Vault, and click Request to Join.

3. The request appears under Pending join requests on an admin's device. Check the device label, then Approve. Approving seals the vault key to that device, so it can decrypt from then on.

4. Set their role: Admin (everything, including members), Editor (add, change and delete hosts) or Operator (connect to hosts and use their saved credentials, but not add or change them). To keep a sensitive host from some members, restrict it to a named list of devices; admins always see every host. See Vaults.

Removing a device

Revoking a member takes effect on the server at once: the device can no longer pull or push anything. It still holds the vault key it had, and like any sync system it keeps whatever it already downloaded. So after revoking a device you no longer trust, click Rotate vault key under Admin actions. That re-encrypts the vault under a new key sealed only to the members who remain. Then change any password that device could read.

Optional features

The installer generates a key for each of these and puts it in /opt/mangossh/vault/.env, so they are available from the start. To turn one off, clear its value and run sudo docker compose up -d in that folder; the related screens then say the feature is not enabled on this server.

To make new values, for example after a suspected leak, run sudo docker run --rm mangossh-cloud-server:VERSION mangossh-cloud-server keygen. Replacing CA_MASTER_KEY this way means rotating every vault's CA afterwards.

Backups and upgrades

Everything the server knows lives in Postgres, in the mangossh_cloud_vault_data Docker volume. Back it up nightly, off the machine, along with /opt/mangossh/vault/.env:

cd /opt/mangossh/vault
sudo docker compose exec -T postgres pg_dump -U mangossh mangossh_cloud_vault | gzip > vault-$(date +%F).sql.gz

Restore into a fresh install with gunzip -c vault-DATE.sql.gz | sudo docker compose exec -T postgres psql -U mangossh mangossh_cloud_vault. Test a restore once. A backup you have never restored is a hope, not a backup.

To upgrade, download the newer bundle and run its installer the same way. It keeps your .env, restarts the server on the new image, and the server applies any new database migrations on start.

Troubleshooting