Troubleshooting playbook#

Local UI does not open#

Run the default launcher first; it selects a free loopback port and opens the browser:

./scripts/hoploom ui

If a fixed port is required and it is occupied, either stop the process that owns it or use automatic selection:

./scripts/hoploom ui --port 0

For a manually opened browser, keep the one-time URL in a private file rather than printing it:

./scripts/hoploom ui --no-open --url-file /tmp/ssh-server-manager-url

The file is mode 600 and is intended for the same local user only.

Remote command reports “No such file or directory”#

hoploom exec treats arguments literally. A full command string such as printf ...; uname -a becomes one executable name unless shell mode is explicit:

./scripts/hoploom exec ALIAS --shell -- 'printf "host=%s\\n" "$(hostname)"; uname -a'

For a normal executable, pass the executable and arguments separately:

./scripts/hoploom exec ALIAS -- uname -a

Sending a file or script#

For a text script, use:

cat local-script.sh | ./scripts/hoploom exec ALIAS --stdin -- sh -s

For a binary artifact, stream raw bytes directly:

cat artifact.tar.gz | ./scripts/hoploom exec ALIAS --stdin-binary -- sh -c 'cat > artifact.tar.gz'

Keep streamed data out of logs and do not use this path for credentials.

Remote Files panel does not load#

Test the same alias first:

./scripts/hoploom server test ALIAS --json
./scripts/hoploom doctor --json

The browser uses the local OpenSSH sftp executable and the remote SFTP subsystem. A successful interactive shell does not guarantee that SFTP is enabled. Directory permission errors are surfaced in the panel; unknown host keys remain a hard failure.

First connection reports “Host key verification failed”#

This can happen before account authentication: the SSH server's host key is not yet trusted on this computer. It is unrelated to whether that account has previously logged in. In your own terminal, run:

./scripts/hoploom connect ALIAS

Under OpenSSH's normal ask policy, compare the displayed fingerprint with the server administrator's trusted value before answering yes or the matching fingerprint. AskPass continues to supply your saved credential. Web checks and agent calls cannot confirm this prompt. An explicit StrictHostKeyChecking=yes policy continues to reject unknown keys until you provision the verified trust record yourself. Changed or revoked keys require investigation; do not delete records or disable verification merely to make the error disappear.

SSH succeeds but a web port is unreachable#

First verify the service on the server itself, then verify the container or process is bound to the intended interface. If localhost works but the public address times out, the cloud security group or upstream firewall needs to allow that TCP port; changing OpenSSH settings will not fix it.

Bare ssh ALIAS fails while hoploom succeeds#

Managed aliases live in the manager's own rendered config, not in ~/.ssh/config, so plain ssh ALIAS treats the alias as a DNS hostname. Under a VPN/proxy fake-IP resolver (Clash, Surge, …) that lookup gets a synthetic answer such as 198.18.x.x and the handshake is dropped — the failure looks like a dead server even though nothing is wrong. Use hoploom connect ALIAS (interactive) or hoploom exec ALIAS -- CMD instead; they apply the managed config and inject vault credentials automatically. Do not add an Include for the managed config to ~/.ssh/config: key-based hosts would half-work, but password auth flows only through hoploom's AskPass, so bare ssh would still prompt.

An AI agent hand-rolls ssh/sshpass instead of using the manager#

Three checks, in order:

1. hoploom doctor — the agent_skill line lists which agent skill directories are linked and warns when a linked copy is older than the running CLI. Re-run install.sh to update stale copies, then restart the agent session so it reloads the skill text.
2. Make sure hoploom resolves by name (command -v hoploom); the installer links it into ~/.local/bin when that directory exists.
3. A one-line nudge — "use hoploom" or "use the hoploom skill" — re-routes an agent that already started down the raw-ssh path.

Never give an agent a password in chat; if a credential is missing, add it through hoploom ui so it lands in the OS vault.