Security and sync

Moshi stores connection metadata, credentials, and preferences through different paths so you can choose the right balance of convenience and security.

Credential storage

Connection passwords, private keys, key passphrases, and fingerprints are stored separately from the saved connection list. On iOS, Moshi uses secure storage for connection credentials.

Deleting a connection clears its related credential entries.

Biometric checks

Two biometric preferences are available:

• Biometric for keys: require Face ID or Touch ID before using saved key material by default.
• Biometric on resume: require a biometric check when returning to Moshi.

Use both if your device is shared or your SSH keys can reach sensitive hosts.

iCloud sync

Moshi can sync settings through iCloud when enabled. Credential sync is a separate toggle and is disabled unless iCloud sync is enabled.

Use settings sync for convenience across devices. Think carefully before enabling credential sync on devices you do not fully control.

Private key handling

When importing a key, prefer a dedicated key for Moshi instead of reusing your main laptop key. Generated Ed25519 keys are a good default.

If you copy a private key out of Moshi, iOS requires biometric confirmation first. Avoid leaving private keys in clipboard history, shared notes, or cloud drives.

SSH host keys

Moshi remembers each host's SSH key the first time it connects, or takes it from the Easy Pair QR, and checks it on every later connection, jump hosts included. If a key changes, Moshi stops and shows Host Key Changed with the old and new fingerprints; nothing is sent until you choose Accept New Key. Tap Cancel unless you know why the key changed, for example because you reinstalled the host.

See Host key verification for what each source means, how to check a fingerprint on the host, and how to forget a stored key.

SSH agent forwarding

Forward SSH Agent lets a host you're connected to ask Moshi to sign with your keys. Anyone with root on that host can make the same requests while you're connected, so turn it on only for hosts you trust. To limit what a host can do, keep Keys on This Key, and set Approval to Ask so every signature needs your Allow. See Agent forwarding.

moshi-hook secrets

On macOS, moshi-hook pair stores host secrets in Keychain by default. On Linux, and on macOS when --store file is selected, secrets are stored in a file with restrictive permissions.

Use file-backed storage for headless machines where Keychain is unavailable, but protect the host account like any other machine with API credentials.

Phones paired to a host

Easy Pair adds each phone's public key to the host account's ~/.ssh/authorized_keys. moshi-hook host list reads that file directly, so it shows exactly the Easy Pair keys that can log in right now, including after you've edited the file by hand.

$moshi-hook host list
$moshi-hook host revoke <id>

Pass an ID from the list to remove that phone's key. Pass only the part before the colon to remove every phone paired through that setup. Keys you added to authorized_keys yourself are not listed and are never touched.

moshi-hook local servers

moshi-hook 0.4.31 and later only accept requests from your own Moshi clients on its local servers: the gateway the app reaches through SSH, and moshi-hook web. Other accounts on the same machine, and web pages open in a browser on it, can't reach them. The Moshi apps, the web client, and SSH port forwarding work as before. Update older daemons.

Two settings loosen this when you need it:

• moshi-hook set allowed-hosts <name> — needed if you open moshi-hook web by a hostname, such as a Cloudflare Tunnel, a .local name, or a reverse proxy. Until it's set, the page shows a 403 that names the exact command. Opening it by IP address needs no setting.
• moshi-hook set allow-other-users on — lets other accounts on the machine connect, for example when the daemon runs under sudo and your clients don't. Use it only on machines where every account is trusted.

Restart the daemon after changing either one.

End-to-end encryption

Agent events, approvals, and usage are the only things moshi-hook sends through Moshi's servers. Turn on end-to-end encryption for a host to seal them there, so only phones that have connected to that host over SSH can read or answer them.

Practical safety checklist

• Use a unique SSH key for Moshi.
• Add the public key only to hosts where mobile access is intended.
• Keep iOS device passcode and biometrics enabled.
• Disable credential sync unless you need it.
• Remove old saved connections when a host is retired.
• Rotate moshi-hook pairing by pairing again if a host is compromised.
• Run moshi-hook host list now and then, and revoke phones you no longer use.
• Don't accept a changed host key you can't explain.
• Turn on end-to-end encryption on hosts whose prompts and approvals you'd rather Moshi's servers never read.