FAQ & troubleshooting#

Install & environment#

hoploom doctor says the vault check failed (Linux). You need an unlocked Secret Service provider — see Platforms. On a headless server either run an unlocked gnome-keyring-daemon or stick to agent-kind credentials.

doctor can't find ssh (Windows). Install the OpenSSH Client optional feature (Settings → Apps → Optional features) and reopen the terminal.

fastapi/uvicorn marked missing. Run ./scripts/bootstrap (source checkout) or reinstall with pipx/uv — the UI dependencies are part of the standard install.

Connections#

server test returns host-key-untrusted. The host key is unknown or changed. Verify the fingerprint out-of-band, accept it once with plain ssh, or clean the stale entry from ~/.ssh/known_hosts. The manager never bypasses verification for you.

authentication-failed but the password is right. Check the username on the profile (server show ALIAS); confirm the server allows password auth (PasswordAuthentication yes on the server side); if the account uses 2FA/OTP the automated password flow will stop at the OTP prompt by design — connect interactively with hoploom connect.

exec says "No such file or directory" for a command that exists. You passed a compound command as one string without --shell. Either hoploom exec a -- ls -la /tmp (separate args) or hoploom exec a --shell -- 'ls -la /tmp | head' (one string).

--reuse doesn't speed anything up on Windows. ControlMaster needs Unix sockets; Windows OpenSSH doesn't support it. The warning is expected — auth is still non-interactive, only slower.

Interactive connect asks for the password even though it's stored. That usually means the AskPass helper couldn't classify the prompt (unusual server banner) or the vault is locked. Run server test ALIAS --json and check error_code; run doctor to confirm the vault backend.

Profiles & credentials#

server add says "server alias already exists". add only creates; it never overwrites an existing profile. Update it with hoploom server edit ALIAS instead — for example --credential LABEL to switch the attached credential, or --hostname/--port to fix the endpoint. No need to remove and re-add.

I typed the wrong password, and credential add-password now says the label exists. Replace the stored secret with hoploom credential edit LABEL --replace-secret — it prompts hidden again. Labels are unique, and a taken label is refused before the password prompt runs, so you never type the secret twice for nothing.

I changed (or am about to change) a server's login password. Run hoploom credential rotate ALIAS in your terminal. It takes the new password at a hidden prompt, waits while you change it on the server, and saves it only after a fresh password-only login with it succeeds — so a typo or a passwd that did not take never replaces a password that still works. Use credential edit --replace-secret only when the server already has the right password and the saved copy is wrong; it does not contact the server.

Web UI#

The URL says "use the one-time URL opened by hoploom ui". The launch token was already used or the server restarted. Stop and rerun hoploom ui for a fresh URL.

Port already in use. hoploom ui --port 0 (automatic selection) or pick another port.

Passkey registration fails. Use a browser with WebAuthn platform-authenticator support (Safari, Chrome, Edge) on localhost, not an IP address. Enroll the master password as a fallback factor.

The Files panel cannot open a directory. Run hoploom server test ALIAS --json first. The browser requires the OpenSSH sftp client locally and an enabled SFTP subsystem on the remote host. It also honors normal directory permissions and refuses unknown or changed host keys. An SSH shell can therefore work while browsing still fails if SFTP is disabled by the server administrator.

Why did a green host become amber? Green is reserved for a connection verified within the last two minutes. After that, the result becomes historical and shows “Last reachable” with its age. Click Test, or browse the host over SFTP, to collect a new result. The manager intentionally does not poll every host in the background.

Data & migration#

Where is everything stored? hoploom doctor prints the paths — database in the platform data dir, rendered config at ~/.ssh/ssh-server-manager.conf, secrets in the OS vault under service ssh-server-manager.

How do I move to a new machine, or keep several in step? Export on the machine that is set up, and import on the other:

hoploom export --output inventory.json   # hosts, saved directories, tunnels
hoploom import inventory.json            # on the other machine: preview
hoploom credential add-password LABEL    # each credential the preview names
hoploom import inventory.json --apply

The file is deterministic JSON with no secrets in it, so it can live in a private git repository or a synced folder and be re-imported whenever it changes (existing hosts stay as they are unless --overwrite). Passwords and key passphrases stay in each machine's OS keychain and are never exported: a host carries its credential's label, and import attaches it only when a credential with that label exists, so create those first. Syncing secrets between machines is deliberately not offered.

Does it ever modify my ~/.ssh/config? No. It renders a separate file that Includes your config last. Never Include the rendered file back from your own config — that's a cycle and rendering will refuse.