WSL2 setup
Muse Code inside WSL2, driven from Windows
When Muse Code is installed inside WSL2 rather than natively on Windows, Helicon routes to the WSL2 distribution and translates paths in both directions. The agent sees Linux paths, the Windows UI shows Windows paths, and you stop hand converting between /mnt/c and C:\ every time something breaks.
Last updated · Markdown version
When you need this page
Muse Code runs natively on Windows now, and if you have that, Helicon uses it and this page is optional. WSL2 still matters for people whose toolchain, dotfiles or project already live inside a distribution, and for anyone who set Muse Code up before native Windows support existed.
What breaks without translation
- The agent reports /home/you/project and the GUI cannot open it.
- You open C:\Users\you\project in the GUI and the agent cannot find it.
- Diffs point at paths that exist on one side of the boundary only.
What Helicon does
- Detects the WSL2 distribution holding your muse install.
- Starts the
muse servehost inside it. - Translates paths both ways so the file viewer, the diffs and the agent agree.
- Prefers native Windows Muse Code when it is installed, and says which route it took.
Checklist
- Open your WSL2 shell and confirm
muse --versionanswers. - Run
muse loginin that same shell. - Install Helicon on Windows with the signed installer.
- Add your project. If the project lives inside the distribution, add its WSL2 path.
Run Muse Code inside WSL2 with the Helicon Windows app
Confirm the CLI answers inside the distribution. Open your WSL2 shell. If this prints a version, the install Helicon should route to is there.
muse --versionSign in from that same shell. Credentials stay with the CLI, inside the distribution. Helicon stores none of its own.
muse loginInstall Helicon on Windows. Run the signed installer from the latest GitHub release. It runs on the Windows host, not inside WSL2.
Add your project. Add the path as the side you work on. Helicon translates between Windows and WSL2 paths both ways, so the file viewer, the diffs and the agent agree.
Frequently asked questions
Do I still need WSL2?
Not for Muse Code itself, which runs natively on Windows. Keep WSL2 if your project or toolchain lives there. Helicon supports both, prefers native when it finds it, and honours HELICON_MUSE_RUNTIME=wsl when you want the WSL2 route regardless.
Which paths should I add as projects?
Add the path as the side you work on. Helicon translates, so either works, and the diffs and file viewer follow.
Does it work with distributions other than Ubuntu?
The routing is per distribution rather than Ubuntu specific. Whichever one holds a working, logged in muse CLI is the one to use.
Keep reading
- WindowsA signed Windows installer for a Muse Code desktop app, with auto update. Runs Muse Code natively on Windows, or inside WSL2 with path translation both ways.
- Muse Code on Windows without WSLMuse Code runs natively on Windows. Here is how to check which route you are on, run it with Windows paths and PowerShell, and keep WSL2 as a fallback.
- Windows developersA signed installer, native Windows Muse Code with PowerShell, and WSL2 path translation when you need it. The Windows setup tax, paid once by the app instead of by you.
Same Muse Code. Same subscription. Better interface.
Free and MIT licensed. Signed Windows installer, universal macOS DMG, and a web build against a daemon you run.