Install and prepare a host

Requirements

• iOS or iPadOS 17 or newer, or Android 10 or newer.
• A Mac, Linux machine, VPS, or other host you can SSH into.
• Network access from the device to the host. Tailscale, a VPN, LAN DNS, public DNS, and bastion hosts can all work.
• mosh-server on the host if you want mosh transport.
• tmux on the host if you want durable workspaces across terminal reconnects.

Install the app

Install Moshi from the App Store on iOS / iPadOS, or from Google Play on Android. The fastest first-host setup is Easy Pair: install moshi-hook on the host, run one setup command, then scan the QR from Moshi.

# macOS
$brew tap rjyo/moshi
$brew install moshi-hook
$brew install mosh tmux
# Debian or Ubuntu
$curl -fsSL https://getmoshi.app/install.sh | sh
$sudo apt install mosh tmux

Both Homebrew and the install script expose moshi next to moshi-hook. Use it to open or attach a tmux session rooted at a project directory:

$moshi .
$moshi ~/projects/app

The command is a thin launcher for tmux new-session -A; it does not start the Moshi daemon or leave a wrapper process behind.

Prepare networking

Plain SSH uses TCP, usually port 22. Mosh uses SSH to start the session, then switches to UDP. If you force mosh or your firewall is strict, open the mosh UDP range on the host.

$sudo ufw allow 60000:61000/udp
$sudo firewall-cmd --add-port=60000-61000/udp --permanent
$sudo firewall-cmd --reload

Moshi does not require a public IP as long as your phone or tablet can reach the host. For mesh VPN setups, see Tailscale.

Choose authentication

Moshi supports password auth and private-key auth. Key auth is usually better for daily use because it avoids typing passwords on mobile and works well with biometric protection.

Easy Pair uses key auth automatically: Moshi generates the private key on the device, sends only the public key to the host setup session, and the host installs that public key in authorized_keys.

When adding a key, Moshi can:

• Generate a new Ed25519 key and copy the public key.
• Import a private key from a file.
• Paste a private key from the clipboard.
• Store an optional passphrase with the connection.

If you set up a connection manually, paste the generated public key into ~/.ssh/authorized_keys on the host.

Easy Pair the host

On the machine you want to connect to, run:

$moshi-hook host setup

Your terminal prints an Easy Pair QR. In Moshi onboarding, tap Easy Pair and scan it. Moshi creates the saved host connection, generates the phone-side private key, and the host installs the public key.

Manual connection fallback

Use New Connection instead when you need a custom private key, password auth, jump host, unusual SSH routing, or advanced mosh options. Fill in:

• Name: optional display name.
• Host: DNS name or IP address.
• Port: usually 22.
• Username: remote login user.
• Authentication: password or key file.
• Connection type: Auto, SSH, or Mosh.

Use Auto unless you know you need to force SSH or mosh. Auto lets Moshi choose the best available transport.

Next setup

After your first terminal works, set up agent notifications:

$brew tap rjyo/moshi
$brew install moshi-hook
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$brew services start moshi-hook

See Agent hooks and Live Activities for the Linux setup and diagnostics.