Platform notes#

CI runs the full test suite on macOS, Ubuntu, and Windows on every push.

macOS#

• Vault: Keychain, no setup needed. The first secret access may show a Keychain permission dialog — click "Always Allow" for your Python/hoploom.
• Passkey reveal: Touch ID via Safari/Chrome WebAuthn.
• OpenSSH: preinstalled (/usr/bin/ssh).
• Connection reuse (--reuse) fully supported.
• Tunnels, mosh, and session transcripts: all available. A tunnel keeps its liveness marker under the runtime directory (/tmp/ssm-<uid>), which must stay short: OpenSSH rejects a ControlPath of 104 characters or more, and hoploom names SSM_RUNTIME_DIR if an override makes it too deep.

Linux#

• Vault: any freedesktop Secret Service provider:
• GNOME: gnome-keyring (default on most desktops)
• KDE: KWallet (5.97+ provides Secret Service; enable it in settings)
• Anything else: KeePassXC with Enable Secret Service integration The collection must be unlocked; normally your desktop login unlocks it.
• Headless / SSH-only servers: there is no unlocked Secret Service by default, so hoploom doctor will fail the vault check. Options:
• Run gnome-keyring-daemon unlocked in your session (e.g. dbus-run-session + gnome-keyring-daemon --unlock)
• Use only agent-kind credentials (ssh-agent / key files without stored passphrases) — those never touch the vault
• Plaintext fallback is deliberately not offered.
• Passkey reveal: requires a WebAuthn-capable browser + authenticator; otherwise enroll the master password.
• Connection reuse fully supported. Runtime sockets live in /tmp/ssm-<uid> (kept short because OpenSSH limits ControlPath length — the same limit applies to a tunnel's liveness marker).
• Tunnels, mosh, and session transcripts: all available. Session logs are written under the data directory; on a headless server they are the reason to have SSM_DATA_DIR somewhere durable.

Windows#

• Vault: Credential Locker (Windows Credential Manager), no setup.
• OpenSSH: install the optional OpenSSH Client feature or winget install Microsoft.OpenSSH.Beta; hoploom doctor verifies it. Git for Windows' MSYS OpenSSH is also supported when it is first on PATH, including credential tests, credential rotate, config rendering and import.
• AskPass: password/passphrase injection uses the ssh-server-manager-askpass.exe console script installed next to your Python — present automatically under pipx/uv or after scripts\bootstrap.cmd.
• Connection reuse (--reuse): not available — Windows OpenSSH lacks ControlMaster Unix-socket support. hoploom prints a warning and each exec authenticates independently (vault auth is non-interactive, so this costs latency, not typing).
• Passkey reveal: Windows Hello via Edge/Chrome.
• Tunnels: supported (a detached ssh -N, terminated with the Win32 API rather than a Unix signal).
• Mosh: not offered on Windows; connect --mosh says so instead of falling back to ssh.
• Session transcripts (connect --log): not available — there is no pty in the standard library on Windows, and --log refuses rather than recording nothing.
• Use scripts\hoploom.cmd from a source checkout; plain hoploom after pipx/uv install.

Data locations#

hoploom doctor prints the effective paths. Defaults:

Beside the database live the audit log (audit.log, plus rotated segments), session transcripts (sessions/), and an optional local GeoIP file (geoip.csv / geoip.mmdb). Running tunnels record their pids in the runtime directory, not in the database.

Overrides for testing/isolation: SSM_DATA_DIR, SSM_RUNTIME_DIR, SSM_ORIGINAL_SSH_CONFIG, SSM_MANAGED_SSH_CONFIG, SSM_GEOIP_CSV, SSM_GEOIP_MMDB, SSM_AUDIT_MAX_BYTES.