Moshi documentation
Everything to run coding agents from your phone: install the app, connect to your own machine over SSH or Mosh, wire up agent hooks, and pair a multiplexer like tmux, Zellij, or Herdr.
Start here
- Step 1
What Moshi does
Moshi is a mobile terminal for long-running coding agents, shells, and tmux sessions on a machine you already control.
read - Step 2
Install and prepare a host
Install the app, prepare SSH or mosh on your Mac, Linux box, VPS, WSL on Windows, or homelab machine, then Easy Pair your first connection.
read - Step 3
Run your first session
Connect to an Easy Pair or manually saved host, start your agent, switch away, and come back without losing the terminal.
read - Step 4
Hooks
Install moshi-hook so supported coding agents can talk to Moshi — and see which integrations include inbox events, approvals, and the native Chat View.
read
Start
What Moshi does
Moshi is a mobile terminal for long-running coding agents, shells, and tmux sessions on a machine you already control.
Install and prepare a host
Install the app, prepare SSH or mosh on your Mac, Linux box, VPS, WSL on Windows, or homelab machine, then Easy Pair your first connection.
Run your first session
Connect to an Easy Pair or manually saved host, start your agent, switch away, and come back without losing the terminal.
Connections
Connections and authentication
Connection types, password and key auth, agent forwarding, jump hosts, mosh port ranges, ET over TCP, custom paths, and credential storage.
Terminal sessions
How Moshi keeps sessions usable on mobile: mosh, SSH fallback, active sessions, reconnect behavior, and the MOSHI_CLIENT flag.
Tailscale
Reach Macs, Linux hosts, and WSL on Windows with no public IP through your tailnet — addresses, mosh over Tailscale, sleep behavior, and common connection failures.
Multiplexer
Multiplexers
Which terminal multiplexers Moshi supports and how deeply — detection, session picker, remote approvals, shortcut panels, hooks, and the moshi launcher.
tmux
Use tmux as the durable workspace behind Moshi, including attach patterns, window switching, and agent workflows.
Zellij
Use Zellij as the durable workspace behind Moshi — detection, session picker, tab and pane shortcuts, and mobile-friendly layout tips.
Herdr
Use Herdr as an agent-aware workspace behind Moshi — detection, session picker, the Herdr shortcut panel, and hook integration.
Jump to…
One sheet that maps the whole session — bounce straight to any tmux window or Herdr tab, with live agent status.
Input
Scrolling and scrollback
Scroll the visible view, raise the in-app scrollback limit, understand mosh’s scrollback gap, and use tmux copy mode for full host-side history.
Voice and dictation
Choose a speech engine, download local models, set languages, use chat mode, and review transcription history.
Gestures
Bind taps, swipes, pinches, drags, and long-presses on the terminal, header, toolbar, and D-pad to actions or custom shortcuts.
Clipboard and copy/paste
Paste into the terminal, select and copy from it, write to the iOS clipboard from the host with OSC 52, and work around wrapped-code copy issues.
Keyboard and shortcuts
Toolbar controls, hardware keyboard shortcuts, Option-as-Meta, custom shortcuts, advanced multi-step bindings, and the D-pad.
CJK and IME input
Korean, Japanese, and Chinese IMEs work through iOS in the terminal, in coding-agent prompts, and in chat mode — plus the locale your host needs for UTF-8 output.
Settings
Licensing and sharing
How an App Store, Google Play, or web purchase becomes a Moshi license, how devices join that license for shared features, and how unified push works.
Personalization
One theme drives the whole app, not just the terminal. Pick a font with proper CJK fallback, a cursor, an app icon, and a UI language.
Free vs Pro
What ships in the free tier, what Pro unlocks, why mosh and automatic tmux or Herdr reattach are reasons people upgrade, and how billing, restores, and license sharing work.
Security and sync
Biometric checks, iCloud settings sync, optional credential sync, Keychain storage, and practical safety boundaries.
Integrations
Agents & Usages
Scan agent approvals, questions, and turn completions in one feed; track Claude Code, Codex, and OpenCode rate-limit windows per account.
Apple Watch
Native watchOS companion: answer approvals, browse the inbox, glance at rate-limit usage, and pin a usage complication to your face.
Image and file paste
One-tap paste from the phone to a coding agent — screenshots, photos, PDFs, logs, anything iOS can hand off.
Hooks
Install moshi-hook so supported coding agents can talk to Moshi — and see which integrations include inbox events, approvals, and the native Chat View.
Hook settings
Every persistent moshi-hook setting, including its default, tradeoffs, and when a daemon restart is required.
Chat View
Turn a live coding-agent terminal into a phone-native conversation without replacing the terminal or sending its transcript through Moshi's servers.
Moshi CLI
The short moshi command — a project tmux launcher and one-shot diff viewer that ships with moshi-hook.
Live Activity
Surface agent events on the iOS lock screen and Dynamic Island while a session is running.
Diff viewer
Review what your agent just changed, right from the iOS app. Served by moshi-hook, diff contents stay on the host.
Browser preview
Open any HTTP server running on your host in the in-app browser, forwarded over SSH. No public tunnel, no port-juggling.
Push notifications and webhooks
Enable push, copy your API token, test notifications, send custom webhook alerts, and fan out agent pushes across devices on the same license.
Files and image sharing
Upload images to get a short, expiring URL you can paste anywhere — and attach arbitrary files to an agent prompt in chat mode.
Help
Troubleshooting
Connection failures, UDP firewalls, locked keychains, missing pushes, CJK locale fixes, dictation problems, and hook diagnostics.
Debugging the gateway
Chat View, diff, and browser preview ride on a local gateway at 127.0.0.1:24543. When they go quiet, this is the page to walk through.
Debugging the session picker
The session picker is built from one command Moshi runs over SSH at connect time. When your sessions are missing, run that same command by hand — it fails in a handful of specific, fixable ways.
Debugging Chat View
Chat View becomes available only after three things line up on the host. Each has its own symptom and its own one-line check.