v2 Remote WSL

Remote WSL over SSH

Manage WSL on a different Windows machine from this app — useful for a home server, a workstation you keep headless, or a lab box. Works from the Windows build and from the macOS build: on a Mac, a configured remote target takes over the whole app, so you manage that host's WSL distros instead of local VMs.

Important: this connects over SSH to a remote Windows host and runs wsl.exe there. It is not for SSH-ing into a Linux machine.

Requirements

On the remote Windows machine:

1. OpenSSH Server installed and running

   Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
   Start-Service sshd
   Set-Service -Name sshd -StartupType Automatic

2. WSL2 installed, with the distros you want to manage. If WSL is missing, the app can trigger wsl --install on the host for you.
3. Key-based SSH authentication set up for your user — the app does not prompt for passwords, so your key must let you connect non-interactively

Verify from your local machine before enabling it in the app:

ssh user@192.168.1.20 wsl --list --verbose

If that prints the remote distro list without asking for a password, you're ready.

Enabling it

Settings → General settings → Remote WSL over SSH

• Turn on Use remote WSL over SSH
• Set Remote SSH target to user@host (or just host, e.g. user@192.168.1.20)
• Save

The app now routes distro operations to the remote machine instead of your local WSL, and the status bar says which host it is talking to.

What works remotely

Listing, starting, stopping, creating, copying, moving, deleting, exporting and packaging distros, snippets and recipes, wsl.conf and .wslconfig editing (through the Settings forms — a remote .wslconfig cannot be opened in a local editor), mounting, the AI assistant and the MCP server all operate against the remote host.

Opening a terminal bridges through your local terminal (Windows Terminal, or Terminal.app on macOS) into an ssh … wsl session; Explorer on macOS opens an SFTP connection to the host.

Not available remotely: the AI Workspace, which needs a local wsl.exe or VM.

Notes and limitations

• Paths are remote paths. Install locations you enter refer to the remote machine's filesystem.
• Performance depends on your link. Large exports/imports move real data over SSH.
• Every remote command token is quoted for the remote shell, so snippets with quotes, pipes and redirects behave the same as locally.
• If the target is malformed or the toggle is off, the app tells you and falls back to local WSL (or local VMs on macOS).
• A slow or unreachable host surfaces as a clear error naming the target, and one failed refresh never wipes the list you already had.

Troubleshooting

"The remote WSL host … could not be reached" The SSH connection didn't establish in time. Check the host name, that it is switched on, that sshd is running, and that ssh user@host works from a terminal without prompting. You can switch back to local WSL from the same message.

Commands fail with an authentication error Key-based auth isn't set up for the user you specified. The app can't answer a password prompt.

"Remote WSL is enabled, but the SSH target is missing or invalid" Use the form user@host or host.