DEV Community

Cover image for How to run Muse Code on a remote server over SSH, with a desktop GUI
Harjot Rana
Harjot Rana

Posted on Originally published at helicon.sh AI-assisted

How to run Muse Code on a remote server over SSH, with a desktop GUI

#ai #ssh #devtools #opensource

Your code lives on a server: a beefy dev box, a cloud VM, the machine under your desk. You want Muse Code to work there, where the files, the toolchain and the CPU are. But you'd rather not spend the day in an SSH terminal scrolling back through agent output.

Helicon 0.18 adds SSH projects: you pick a folder on a remote machine, and Helicon runs Muse Code there over ssh, while you get the desktop app on your laptop: threads in a sidebar, readable approvals, and inline diffs.

This guide sets it up in about 10 minutes.

How it works

When you start a thread in an SSH project, Helicon runs this on your laptop:

ssh <host> 'cd /path/to/project && exec muse serve'
Enter fullscreen mode Exit fullscreen mode

Muse Code runs on the server, inside the project folder, and talks to Helicon over the SSH connection using the Muse Session Protocol (MSP), the same protocol it speaks to any local client. Nothing is synced or copied: the code never leaves the server.

A few consequences worth knowing:

  • The server's Muse login is the one used. Whatever account you signed into with muse login on the server is what your SSH threads run on. Helicon's local account profiles don't apply to SSH projects.
  • Your laptop needs to stay connected. Muse runs as part of the SSH session, so if your laptop sleeps or the network drops, that session ends. Helicon notices within about 45 seconds.
  • Your SSH config is respected. Host aliases, ports, users, jump hosts and keys all come from ~/.ssh/config, the same as when you type ssh yourself.

1. Make ssh work without a password

Helicon never types a password or answers a prompt; it runs ssh in batch mode. So the first step is a key.

On your laptop:

ssh-keygen -t ed25519            # skip if you already have ~/.ssh/id_ed25519
ssh-copy-id you@devbox.example.com
Enter fullscreen mode Exit fullscreen mode

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

Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519
Enter fullscreen mode Exit fullscreen mode

Check it: this should print ok without asking you anything.

ssh devbox echo ok
Enter fullscreen mode Exit fullscreen mode

If it asks you to confirm the host key, answer yes once. Helicon can't answer that question for you, and will tell you so if you skip it.

On Windows: Helicon uses Windows' own OpenSSH (ssh.exe), not the one inside WSL. Keys and config belong in %USERPROFILE%\.ssh. If your keys only live in WSL, copy them over, or run ssh-keygen in PowerShell.

2. Install Muse Code on the server

On the server, install the muse CLI the way you normally would, then sign in once:

muse login
Enter fullscreen mode Exit fullscreen mode

Now make sure muse is on the PATH for non-interactive SSH commands, which is what Helicon uses. From your laptop:

ssh devbox 'command -v muse'
Enter fullscreen mode Exit fullscreen mode

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

3. Add the project in Helicon

  1. Open Helicon (0.18 or newer) and click Add project.
  2. Choose SSH host.
  3. Type the host: devbox, or you@devbox.example.com.
  4. Browse the server's folders, starting at your home folder, and pick the project.

The project shows up in the sidebar like any other. Start a thread, and Muse Code is working on the server.

When something goes wrong

Helicon reports what ssh itself said, so the error usually tells you the fix:

Helicon says Fix
Host key verification failed Run ssh devbox once in a terminal and accept the host key
Permission denied (publickey) The key isn't on the server: rerun ssh-copy-id, or check IdentityFile
Could not find ssh on this machine Install OpenSSH (on Windows: Settings, Optional features, OpenSSH Client)
Connection refused / timed out Check the host, port and VPN with ssh devbox echo ok
Muse not found when starting a thread ssh devbox 'command -v muse' prints nothing: fix PATH as in step 2

What SSH projects don't do yet

In 0.18, SSH projects run threads, show diffs and approvals, and list past sessions from the server. These aren't available for them yet:

  • the file viewer panel
  • the skills list
  • attaching files (images still work)
  • creating a new remote folder or cloning a repo onto the server from Helicon

Create folders and clones over SSH first, then add them.

SSH projects or the remote daemon?

Helicon has two ways to use a remote machine:

  • SSH projects (this guide): the Helicon app runs on your laptop, and only Muse runs on the server. Mix local and remote projects in one window.
  • Remote daemon: the whole Helicon server runs on the remote machine, and you open it in a browser. Better when you want to reach it from any device.

Try it

Helicon is free and open source (MIT) for Windows, macOS and Linux: helicon.sh. SSH projects were contributed by Hoà Dinh in #56.

Helicon is an unofficial community project, not affiliated with Meta.

Top comments (0)