---
title: "Run Muse Code on a remote server over SSH, with a GUI"
url: https://helicon.sh/guides/muse-code-over-ssh
description: "Point Helicon at a folder on a remote machine and Muse Code runs there over ssh, while you keep threads, approvals and diffs in a desktop app on your laptop."
updated: 2026-09-28
site: Helicon
---

# 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.

## 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.

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

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

```text
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.

> On Windows, Helicon uses Windows' own OpenSSH (ssh.exe), not the one inside WSL. Keys and config belong in %USERPROFILE%\.ssh.

## 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:

```bash
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.

## Run Muse Code on a remote server over SSH with Helicon

1. **Set up a key-based ssh login** ssh to the host must work without a password prompt.
   ```sh
   ssh devbox echo ok
   ```
2. **Sign in to Muse Code on the server** Install the muse CLI there and sign in once.
   ```sh
   muse login
   ```
3. **Check muse is on the remote PATH** Non-interactive ssh commands must find it.
   ```sh
   ssh devbox 'command -v muse'
   ```
4. **Add the SSH host in Helicon** Add project, then SSH host, then type the host name.
5. **Pick the folder and start a thread** Browse the server's folders from your home folder and choose the project.

## Frequently asked questions

### Does my code leave the server?

No. Muse Code runs on the server and reads the files there. Helicon only receives the conversation, tool output and diffs over the ssh connection.

### Which Muse account do SSH projects use?

Whichever account is signed in with muse login on the server. Helicon's local account profiles do not apply to SSH projects.

### Does the agent keep running if my laptop sleeps?

No. Muse runs as part of the ssh session, so the session ends when the connection drops. Use the remote daemon if you need it to outlive your laptop.

### Which version of Helicon do I need?

0.18.0 or newer.

## Related

- [Remote daemon](https://helicon.sh/guides/remote-daemon-setup): Put the Helicon daemon and the muse CLI on the machine that holds your code, then open the same UI in a browser from anywhere you trust the network.
- [Remote daemon and web UI](https://helicon.sh/features/remote-daemon): The same Helicon UI ships as a web app pointed at a daemon on another machine, so a laptop can supervise Muse Code running on a workstation or a server.
- [Remote development](https://helicon.sh/use-cases/remote-development): Run the daemon and the muse CLI on the machine that holds the repository, then supervise from a browser on a laptop. Same UI, same sidebar, same approvals.

---

Helicon is a free, MIT licensed, unofficial community client for Meta's Muse Code CLI. Not made, sponsored or endorsed by Meta. Source: https://helicon.sh/. Machine readable index: https://helicon.sh/llms.txt