Install Moshi Desktop

Moshi Desktop is the browser-based control room for your coding agents. There is no separate download: Desktop ships inside the same moshi-hook binary that powers the phone app, so installing one binary gives you everything on macOS, Linux, and Windows — no account, no pairing, no relay.

This page walks the whole setup: the server/client split, running both locally, installing the agent hooks (required for Chat View and approvals), and connecting to remote machines.

Server and client — what runs where

One binary plays two roles, and knowing which is which makes everything else obvious:

• The server is the daemon — moshi-hook serve. It runs on every machine where your agents live. It owns the local socket that Claude Code, Codex, and the other agents post events to, and it serves the host gateway (structured web APIs: workspaces, transcripts, approvals, dev-server ports) on 127.0.0.1:24543 — loopback only, never a network port.
• The client is Desktop itself — the web UI you get from running bare moshi. It serves the embedded interface on http://127.0.0.1:24544, opens your browser, and proxies every API and WebSocket request to a daemon: the local one directly, remote ones through your own SSH.

Step 1 — install the binary

The one-line script works on macOS, Linux, and WSL; Homebrew is nicer on a Mac you use daily:

# any supported host
$curl -fsSL https://getmoshi.app/install.sh | sh
# or Homebrew on macOS
$brew tap rjyo/moshi && brew install moshi-hook

Every install method, including the experimental native Windows preview, manual binaries, and updating, is covered in Install moshi-hook.

Step 2 — install the agent hooks

This step is required, and easy to miss: without it, Desktop can show you terminals but knows nothing about your agents. moshi-hook install writes hook entries into the config files of every supported agent it finds — that's how session starts, prompts, approvals, and transcripts reach the daemon, and how Chat View, the inbox, and remote approvals work at all.

$moshi-hook install

Run it on every machine where agents run — your laptop and each remote box. It's non-destructive (your own hooks are left alone), and it needs no account or pairing; pairing is only for the phone app's push notifications. See Agent hooks for what gets installed where.

Step 3 — run it locally

$moshi
→ opens http://127.0.0.1:24544 in your browser

That's the whole thing. Bare moshi starts the client in the foreground and finds itself a server automatically: if a persistent daemon is already running it reuses it, otherwise it starts a temporary one and stops it again when you Ctrl-C. Pass --no-open to print the URL without launching a browser.

For daily use, run the daemon persistently so agent events keep flowing when the Desktop tab is closed:

# Homebrew on macOS
$brew services start moshi-hook
# systemd on Linux / WSL, logon startup on Windows
$moshi-hook service install

Step 4 — connect to a remote machine

Desktop reaches other machines over your own SSH — the same keys and config aliases you already use. No relay, no account: if ssh <host> works from your terminal, that host works in Desktop.

Prepare the remote box once (it's the server role only):

$curl -fsSL https://getmoshi.app/install.sh | sh
$moshi-hook install
$moshi-hook service install

Then, in Desktop on your local machine, open the host switcher in the sidebar footer and type the SSH destination — a ~/.ssh/config alias, user@hostname, or a Tailscale MagicDNS name. Desktop bridges to the remote daemon's loopback gateway through ssh -W, keeps the connection warm with SSH connection reuse, and remembers the host for next time. Terminals attach over ssh -t, and detected dev-server ports are tunneled back automatically so previews open at http://localhost:<port>.

A few things worth knowing:

• Key-based auth is required. The bridge runs SSH in batch mode, so hosts that need a password or an interactive 2FA prompt fail fast instead of hanging. If a host errors with Permission denied (publickey), verify plain ssh <host> works from a terminal first — agent-guarded keys (1Password, Secretive) may need an approval there before the bridge can use them.
• The remote needs a recent daemon. Desktop refuses to switch to a host running moshi-hook older than v0.3.1 and tells you so — run moshi-hook update (or brew upgrade moshi-hook) on the remote.
• Your bytes never leave your SSH connection. Terminal traffic, transcripts, diffs, and previews go from the remote host to your browser through your own tunnel and nowhere else.

Recap

If something doesn't come up — the install download fails, a host shows unreachable, agents don't appear — see Troubleshooting.