Connections and authentication

Saved connections are the entry point for terminals. Each connection stores routing details and non-secret metadata in app storage. Credentials are stored separately in iOS secure storage.

Basic fields

• Icon: the picture shown for the connection on Home, on its session cards, and beside its host in the Inbox. Tap the square beside Name to pick Server, Cloud, Laptop, Mac mini, Mac Studio, or Desktop.
• Name: optional label shown in the app. If empty, Moshi can use user@host.
• Host: IP address, DNS name, Tailscale name, or other reachable host.
• Port: SSH port, commonly 22.
• Username: remote login user.
• Authentication: password or key file.
• Connection type: Auto, SSH, Mosh, ET, or Osewa.

VPN

Moshi has no built-in VPN integration and does not need one. Any OS-level VPN — Tailscale, WireGuard, corporate VPN — works transparently: connect the iOS device to the VPN, then enter the host's VPN-side address in the Host field as a normal SSH or mosh target. For Tailscale specifically, see Tailscale.

Connection type

Auto is the default and the best starting point. Moshi picks a transport for you, trying mosh, then ET, then SSH.

SSH forces a plain SSH terminal. Use this for hosts where UDP is blocked, where mosh is not installed, or when you need SSH-only routing such as a jump host.

Mosh forces mosh transport and exposes mosh-specific fields such as UDP port range and custom mosh-server path.

ET forces Eternal Terminal transport. Like mosh, an ET session survives network changes, sleep, and app kills — but it runs over TCP instead of UDP, so it reconnects on networks where mosh's UDP traffic is blocked. ET is a Pro feature and is currently experimental.

Osewa connects through Osewa, over QUIC or TLS over TCP. It's experimental, Auto never picks it, and the host needs Osewa and moshi-hook.

To try a different transport once without editing the connection, long-press it on Home and choose Connect With, then Auto, SSH, Mosh, ET, or Osewa. That launch uses the transport you picked; the saved connection type stays as it was.

Password auth

Password auth stores the password for that connection. Use it for simple hosts, temporary machines, or systems where SSH keys are not available.

If you later switch the connection to key auth, Moshi clears the opposite saved credential for that connection.

Key auth

Key auth supports generated, imported, or pasted private keys. Moshi validates that you are adding a private key, not a public key, and shows the fingerprint after a key is selected.

When a key is present, tapping the key row lets you copy the public key if Moshi can extract it. Copying the private key requires biometric confirmation.

Host key verification

Moshi checks every SSH server's host key, so another machine on the network can't pose as your host and collect your password or key.

First connection. There is no prompt. Moshi trusts the key the host presents and remembers it for that host and port. Every saved connection that reaches the same host, as a target or as a jump host, shares that one key.

Easy Pair. The QR printed by moshi-hook host setup (moshi-hook 0.4.32 or later) includes the host's key fingerprint, so pairing records the key before you ever connect. The first connection is then verified against the QR instead of trusted on sight.

Once a key is recorded, the connection form shows a Host Key row with the fingerprint, the key type, and where it came from:

• Trusted on first connection
• Verified by Easy Pair QR
• Accepted after a change

When a host key changes

If a host presents a different key, Moshi stops before sending anything and shows Host Key Changed, with the key Moshi pinned and the key the host presented. The session shows Host key changed and does not reconnect on its own.

• Cancel keeps the old key and leaves the connection closed. Choose this if you don't know why the key changed.
• Accept New Key replaces the stored key and retries the connection.

A legitimate change usually means the host was reinstalled, rebuilt, or had its SSH keys regenerated, or the address now points at a different machine. Before accepting, compare the presented fingerprint with the host's own keys, checked from the host itself or over a connection you already trust:

$for f in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf "$f"; done

Reset a trusted key

To clear a stored key, for example before reconnecting to a host you know was reinstalled, edit any connection to that host and tap the × on its Host Key row, then Forget. The next connection trusts whatever key the host presents, the same as a first connection. Alternatively, run moshi-hook host setup on the reinstalled host and scan the new Easy Pair QR: pairing replaces the stored key with the one in the QR, so you skip the trust-on-first-connection step.

Agent forwarding

Forward SSH Agent lets the remote host use your SSH keys from Moshi, so git push, git pull, and SSH commit signing work on the server without ever copying a key onto it.

The switch appears on the connection form only when Connection type is SSH and Authentication is key auth. It is off by default, and is available on the free plan.

When the switch is on, two more choices appear:

• Keys: This Key (the default) offers only the connection's own key. All Keys offers the connection's key first, then every key in SSH Keys, which helps when you sign commits or reach GitHub with a different key than the one you log in with.
• Approval: Auto (the default) signs without asking. Session asks once per key each time you connect. Ask asks before every signature.

When Moshi asks, the alert names the host and the key and says what is being signed, such as signing in as a user or signing a Git commit or tag. Tap Allow or Deny. A request you don't answer within a minute, or one that arrives while Moshi is in the background, is denied.

What gets forwarded:

• Only keys stored in Moshi. Moshi is not a bridge to an external or hardware SSH agent.
• PIV and security-key authentication cannot be forwarded.
• The matching public key must be registered with GitHub, or whichever service you are reaching from the host.

On the host, sshd must permit forwarding — AllowAgentForwarding yes in sshd_config. This is the OpenSSH default but is often turned off in hardened configurations.

Check it after connecting:

$echo "$SSH_AUTH_SOCK"
$ssh-add -L

ssh-add -L should print the public keys Moshi is offering. If SSH_AUTH_SOCK is empty, forwarding did not reach the host — Moshi sends the request without waiting for a reply, so a server that refuses it fails quietly rather than showing an error.

Commit signing

Signing with the forwarded key needs Git's SSH signing format. A GPG signing setup will not touch the SSH agent.

$git config --global gpg.format ssh
$git config --global user.signingkey "ssh-ed25519 AAAA..."
$git config --global commit.gpgsign true

Jump hosts

Jump host settings are available when the connection type is SSH. Use the form:

$bastion@example.com:22
$deploy@10.0.0.5:2222

Use SSH mode when you need a bastion. Mosh requires UDP reachability to the final session and is usually not compatible with a simple SSH jump-host path.

Mosh options

When connection type is Mosh, you can set:

• UDP port range: for hosts where only a specific range is open.
• Mosh path: custom path to mosh-server, for example /opt/homebrew/bin/mosh-server.

Leave these blank unless your host needs them.

ET options

When connection type is ET, you can set:

• TCP port: the port your etserver listens on. Leave blank to use Eternal Terminal's default of 2022.

ET needs the Eternal Terminal server (etserver) running on the host, the same way mosh needs mosh-server. Install it from eternalterminal.dev — for example brew install eternal-terminal on macOS — and start etserver before connecting.

Reordering and editing

Saved connections can be edited, duplicated, deleted, and reordered from the home list: long-press a connection for its menu. Deleting a connection also clears its saved password, private key, passphrase, and fingerprint entries, and forgets the host's key once no other saved connection reaches that host.