Guides

Run Muse Code on a remote server over SSH

Add an SSH host as a project in Helicon 0.18 or newer. Helicon runs muse serve on the remote machine inside the project folder over a passwordless ssh connection and speaks MSP over it, so the code never leaves the server. You need a key-based ssh login and the muse CLI signed in on the server.

Last updated 28 September 2026 · Markdown version

How it works

When you start a thread in an SSH project, Helicon runs ssh <host> 'cd /path/to/project && exec muse serve' on your laptop. Muse Code runs on the server, inside the project folder, and talks to Helicon over the SSH connection using MSP, the same protocol it speaks to any local client. Nothing is synced or copied.

The server's Muse login is the one used. Local account profiles do not apply to SSH projects.
Your laptop has to stay connected. If it sleeps or the network drops, the session ends, and Helicon notices within about 45 seconds.
Host aliases, ports, users, jump hosts and keys come from your ~/.ssh/config, as when you type ssh yourself.

Make ssh work without a password

Helicon runs ssh in batch mode: it never types a password or answers a prompt. Create a key and copy it to the server.

ssh-keygen -t ed25519
ssh-copy-id you@devbox.example.com

Give the host a short name in ~/.ssh/config:

Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519

Then ssh devbox echo ok should print ok without asking anything. If it asks you to confirm the host key, answer yes once.

Install Muse Code on the server

Install the muse CLI on the server and run muse login there once. Then check that muse is on the PATH for non-interactive ssh commands, which is what Helicon uses:

ssh devbox 'command -v muse'

If that prints nothing, your shell only sets PATH for interactive logins. Add the folder that holds muse to PATH in ~/.zshenv for zsh, or near the top of ~/.bashrc for bash.

When something goes wrong

Helicon says	Fix
Host key verification failed	Run `ssh devbox` once in a terminal and accept the host key
Permission denied (publickey)	The key is not on the server: rerun ssh-copy-id or check IdentityFile
Could not find ssh on this machine	Install the OpenSSH client
Connection refused or timed out	Check the host, port and VPN with `ssh devbox echo ok`
Muse is not found when a thread starts	Fix PATH on the server as above

What SSH projects do not do yet

The file viewer panel.
The skills list.
Attaching files. Images still work.
Creating a remote folder or cloning a repository onto the server from Helicon.

Threads, approvals, inline diffs and past sessions on the server all work. Create folders and clones over ssh first, then add them.

SSH projects or the remote daemon

With SSH projects the Helicon app runs on your laptop and only Muse runs on the server, so local and remote projects share one window. With the remote daemon the whole Helicon server runs on the remote machine and you open it in a browser, which suits reaching it from any device.