Troubleshooting

SSH cannot connect

Check the basics from another machine first:

$ssh user@host -p 22

If plain SSH fails outside Moshi, fix host reachability, username, port, firewall, DNS, VPN, or credentials first.

Mosh cannot connect

Mosh needs SSH for startup and UDP for the live session. If SSH works but mosh does not:

• Confirm mosh-server exists on the host.
• Open UDP 60000:61000 or the custom range you configured.
• Check whether the current network blocks UDP.
• Try connection type SSH as a fallback.
• Set a custom mosh path if mosh-server is installed outside PATH.

mosh-server is installed but not found

Mosh bootstraps through a non-interactive SSH session, which does not load ~/.zshrc, ~/.bashrc (interactive section), or ~/.profile. A Homebrew-installed mosh-server (/opt/homebrew/bin on Apple Silicon, /usr/local/bin on Intel/Linuxbrew) often isn't on the non-interactive PATH.

Two fixes:

1. Add the path to a file the non-interactive shell does load:

# zsh: ~/.zshenv
# bash: top of ~/.bashrc, before any interactive guard
$export PATH="/opt/homebrew/bin:$PATH"

2. Or set Mosh path in the connection's Mosh options to the absolute path:

$/opt/homebrew/bin/mosh-server
$/usr/local/bin/mosh-server

Tailscale connections

For Tailscale-specific issues — wrong address, "unable to authorize", OS Error 4, Mac sleep behavior — see Tailscale.

Jump host fails

Jump hosts are available for SSH connections. If you configured a jump host while forcing mosh, switch the connection type to SSH or connect through a network path where the final host is directly reachable.

Key import fails

Moshi expects a private key. Public keys starting with ssh-rsa, ssh-ed25519, ecdsa-sha2-*, or PEM public-key blocks are rejected in the private-key field.

If a private key has a passphrase, enter the passphrase in the connection form.

moshi-hook install download fails (403 / Cloudflare challenge)

The install.sh script and brew install moshi-hook both pull binaries from cdn.getmoshi.app (Cloudflare). On rare networks Cloudflare's bot protection serves a JS challenge to curl, which returns HTTP 403 with a cf-mitigated: challenge header.

Confirm the challenge is what you're hitting:

$curl -v https://cdn.getmoshi.app/hook/v0.1.4/moshi-hook_Linux_x86_64.tar.gz 2>&1 | head -30

If the response includes HTTP/2 403 and cf-mitigated: challenge, no curl flag will get past it — the challenge requires a real browser to solve.

Manual install:

1. Open the URL printed by the install script in a browser. The browser solves the challenge and downloads the tarball.
2. Move the file onto the host (scp, USB, AirDrop, etc.).
3. Extract and place the binary on PATH:

$tar -xzf moshi-hook_Linux_x86_64.tar.gz
$sudo mv moshi-hook /usr/local/bin/
$moshi-hook pair --token <token>
$moshi-hook install

If you hit this from a region or PoP that consistently challenges, send a curl -v capture to Settings -> Support so the CDN rule can be tuned.

macOS Keychain blocks moshi-hook

If pairing from SSH or a locked macOS session fails, unlock the login keychain:

$security unlock-keychain ~/Library/Keychains/login.keychain-db
$moshi-hook pair --token <token>

For headless use, pair with file storage:

$moshi-hook pair --token <token> --store file

Agent events do not appear

Run:

$moshi-hook status
$moshi-hook logs -f
$moshi-hook install

Confirm the daemon is running, the host is paired with the token from your Moshi app, and the agent you are using is one of the supported installers.

Push notifications do not arrive

• Confirm iOS notification permission is enabled for Moshi.
• Confirm notifications are not paused in Moshi settings.
• Send a test notification from the settings screen.
• On simulator, test push delivery is not representative of a real device.
• For agent events, confirm moshi-hook serve or the macOS service is running.

Live Activity does not update

Check Settings -> Agent Hooks:

• Live Activity toggle is enabled.
• The demo Live Activity can start.
• Agent events are reaching the inbox.

Live Activities depend on iOS support and system policy. If the inbox updates but the Live Activity does not, restart the app and test with the demo action.

Pro is not recognized on a new device

A Pro purchase (subscription or lifetime) is tied to your Apple ID and works on every device signed in to the same Apple ID. After installing Moshi on a new device, open Settings -> Pro and tap Restore.

If Restore does nothing, confirm the device is signed in with the Apple ID that made the purchase. Restore brings back entitlements only — to also bring saved connections, enable iCloud sync in Moshi settings on both devices.

Korean or CJK characters do not render

The remote shell needs a UTF-8 locale for CJK output to render. Confirm with locale on the host; if it shows C or POSIX, set LANG=en_US.UTF-8 (or the equivalent for your locale) in ~/.zshenv or the non-interactive section of ~/.bashrc. See CJK and IME input for the full setup.

Dictation quality is poor

• Try a different Whisper model.
• Pin the language instead of using automatic detection.
• Use chat mode for natural-language agent prompts.
• Turn off auto-send while testing so you can edit before submission.

Need help

Use Settings -> Support to email support with the host OS, connection type, Moshi version, and the exact error shown in the app.