Windows & WSL

One rule explains every choice on this page:

The server runs where the code is.

A repo inside WSL is driven by a server inside WSL. A repo on C:\ is driven by a server on Windows. Never point a Windows-side server at a \\wsl.localhost\… share: claude, git and file watching would all go through the 9p bridge, and everything gets slow and unreliable. Helmry has a proper mechanism for the WSL case, which is what the rest of this page is.

None of this applies on macOS or Linux — there is one filesystem and nothing to choose.

The default: a Windows app

Helmry.exe hosts the server on Windows, in-process. It never probes for WSL unless you ask it to. git, the terminal (ConPTY) and the workspace all run natively, and repos on C:\ open as they are.

The one extra requirement is Claude Code on Windows — either the native claude.exe, or the npm install (a claude.cmd shim, which Helmry resolves to node.exe plus the CLI’s own entry point, because a batch file cannot be spawned without a shell and a shell would parse your prompt).

If Claude is missing, agents cannot start; the health endpoint reports it and the app tells you.

When your project lives inside WSL

Pick the distribution when you open the repository, and everything that repo’s agents do — claude, the terminal, git, uploads — happens on the Linux side. See Per-agent environments just below; that is the whole mechanism, and there is nothing to set up first.

Observed sessions must have hooks installed inside the distribution, not on Windows:

wsl -d <distro> -- bash -ic "helmry install-hooks"

Removed: attach mode. Earlier versions had a second, application-wide answer — a Server menu (Ctrl+Shift+O) that pointed the whole window at a server inside one distro, plus the HELMRY_HOSTING, HELMRY_WSL_DISTRO, HELMRY_WSL_START and HELMRY_REMOTE_URL variables. It is gone. The choice it made was one distro for everything, made before the app had loaded; per-agent environments make the same choice per repository, several at a time, and work the same way in a browser as in the desktop app. If you had a saved choice in %APPDATA%\Helmry, it is simply ignored now — open the repo again and pick its environment.

Per-agent environments

You do not have to choose one side for everything. A repo — and therefore an agent — can be bound to local or to one WSL distribution, and both kinds can sit in the same fleet.

New agent (or Add repository) → the Environment select → WSL — scan for distributions… (the one explicit probe) → pick e.g. WSL · Ubuntu-22.04. Helmry finds or starts a small satellite server inside that distro, and the folder browser and repo list re-root inside it. Pick the repo and launch.

From then on everything routes to that environment automatically: the conversation, stop and rewind, permissions, slash commands, transcript recovery, image uploads, the embedded terminal, git badges, the file-edit feed, Diff & review, the project-wide Changes rail (groups tagged WSL · <distro>) and the Files rail. An agent’s environment is fixed for its life, and reloading the page reconnects the satellite in the background.

Connecting is always something you or a dialog did — background polling never raises a satellite.

Known limitations

• Hiding a repo is path-keyed. Hiding /home/you/proj also hides a same-named path in another distribution. Cosmetic.
• The Ports panel lists the host machine’s listeners only, not a distro’s.
• Auto-installing Helmry into a distro (for a distro where it is missing) downloads a prebuilt Linux build from the private release feed, so it needs the update token configured first (see Install & updates).
• WSL1 is not supported.
• Satellites are identified by a health check and started on a free port chosen by the host — never 4317, because WSL2 distributions share one network namespace.