Orca on Windows with WSL repos: use SSH, not \\wsl.localhost
The problem If your repos live inside WSL, the best way to use Orca on Windows is to run an SSH server in WSL and add it to Orca as an SSH host. That way git, agents, terminals, file access and file watching all happen
The problem
If your repos live inside WSL, the best way to use Orca on Windows is to run an SSH server in WSL and add it to Orca as an SSH host. That way git, agents, terminals, file access and file watching all happen inside Linux, and Windows only draws the UI. The whole setup took me about 15 minutes.
Orca is an open-source desktop app that runs coding agents like Claude Code and Codex in parallel, each in its own git worktree. When you add a project on Windows, it gives you two choices: a remote host (SSH or an Orca server) or Local Windows (this computer).
Pick Local Windows and you get a folder picker that starts on your C: drive. My repos aren't there. They live in my WSL home directory, which is where Linux tooling and git run fastest. This post explains why I didn't just point that picker at WSL, and walks through the SSH setup step by step, including every error I hit along the way.
Two ways to open a WSL repo in Orca
Both options work. What separates them is how much of Orca's work has to cross from Windows into WSL.
In Option A, every file read from the UI crosses the 9P bridge. In Option B, only the SSH connection crosses from Windows.
Option A: Local Windows + \\wsl.localhost
You can type a path like \\wsl.localhost\Ubuntu\home\you\repo into the Local Windows folder picker. Orca recognizes it as a WSL repo. Terminals launch through wsl.exe -d <distro> (Orca terminal docs), and Git commands run inside WSL rather than with Windows git.exe (PR #30693). Those are the heavy parts, and they run natively.
The rest crosses the 9P bridge, the network filesystem Windows uses to reach WSL files. That covers opening files in the editor, the file explorer, reading files for diffs, and some background scans of a worktree's Git folder (PR #34632). 9P is much slower than native disk access, and it's the usual cause of laggy editors on WSL (Windsurf's WSL notes). File watching is the other gap: the main WSL-support PR left watching of WSL worktree folders for later, so new worktrees may only show up after a manual refresh (PR #8287). WSL support is also fairly new, and recent fixes are still landing, such as Orca wrongly reporting WSL as unavailable when wsl.exe was slow (PR #26678).
Option B: SSH into WSL
With an SSH host, Orca creates the worktree on the host, runs agents there over SSH, and syncs file events back so the editor and diff still feel local (Orca SSH docs). Orca runs its own server on each SSH host (settings reference), so file reads and file watching happen inside Linux too. The "remote" machine is your own PC, so SSH to localhost adds almost no delay. It's the same model as VS Code's Remote-WSL.
Local Windows + \\wsl.localhost
|
SSH into WSL | |
|---|---|---|
| Git, terminals, agents | Run inside WSL | Run inside WSL |
| Editor, explorer, diff reads | Over the 9P bridge | Through Orca's server in Linux |
| File watching | Limited; new worktrees may need a refresh | Synced by Orca's server |
| Setup | None | About 15 minutes |
| Maturity | Newer, fixes still landing | Orca's main remote path |
I haven't benchmarked the two. This comparison is about where each piece of work runs. If you want to compare them yourself, add one real repo with Option A, use it for ten minutes, and watch the file explorer and diffs. For big repos or lots of parallel worktrees, I went with SSH.
Step 1: Run an SSH server inside WSL
All of these commands run in your WSL terminal. I used Ubuntu.
- Install the SSH server and a build toolchain. Orca's remote terminals need
node-pty, which compiles from source on Linux and needs a C++ compiler (Docker's Orca guide).
sudo apt update && sudo apt install -y openssh-server build-essential python3
- Move SSH to port 2222. This keeps it from colliding with a Windows OpenSSH server on port 22. Open the config:
sudo nano /etc/ssh/sshd_config
Find #Port 22 and change it to Port 2222, with no # at the start.
- Start the service and enable it at boot:
sudo systemctl enable --now ssh
This needs systemd, which current Ubuntu on WSL turns on by default. If yours doesn't have it, add [boot] and systemd=true to /etc/wsl.conf, then run wsl --shutdown from PowerShell.
-
The gotcha: on recent Ubuntu releases, SSH is socket-activated.
ssh.socketdecides which port to listen on, and it ignores your edit until systemd reloads it. Reload it explicitly:
sudo systemctl daemon-reload
sudo systemctl restart ssh.socket
- Check that it's listening on 2222:
sudo ss -tlnp | grep ssh
You want to see :2222. If you still see :22, step 4 didn't take effect.
- Install and log in to your agents (Claude Code, Codex, whatever you use) inside WSL. They run on the SSH host, so a copy installed only on Windows won't be found.
Step 2: Connect from Windows with a key
Orca runs on Windows, so Windows is the SSH client and keeps the private key. WSL only needs the public half.
- Create a key in PowerShell (skip this if you already have
id_ed25519):
ssh-keygen -t ed25519
This writes id_ed25519 (private) and id_ed25519.pub (public) to C:\Users\<you>\.ssh\.
- Back in WSL, authorize that key.
~/.sshusually doesn't exist yet, so create it first. WSL can read your Windows files under/mnt/c, so there's nothing to copy and paste:
mkdir -p ~/.ssh
chmod 700 ~/.ssh
cat /mnt/c/Users/<your-windows-user>/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
Don't skip the chmod lines. If the folder or file permissions are too open, sshd silently ignores authorized_keys and asks for a password.
- In PowerShell, create
C:\Users\<you>\.ssh\config. Watch the encoding: Windows PowerShell 5.1 writes UTF-16 by default (>,Out-File), and OpenSSH can't read that. Set it explicitly:
@"
Host wsl
HostName localhost
Port 2222
User <your-wsl-user>
IdentityFile ~/.ssh/id_ed25519
"@ | Set-Content -Path "$env:USERPROFILE\.ssh\config" -Encoding ascii
Run whoami in WSL to get your Linux username. If you'd rather use Notepad, make sure it doesn't save the file as config.txt. The name has to be exactly config.
- Connect once from PowerShell:
ssh wsl
The first time, SSH asks Are you sure you want to continue connecting (yes/no/[fingerprint])?. Type the whole word yes. Just pressing Enter fails with Host key verification failed, which looks like an error but only means the question wasn't answered. After that, you should land in your Ubuntu shell without a password prompt. If you see a password prompt, the key isn't being used: go back to step 2.
Step 3: Add the host and project in Orca
- Open Settings β SSH. Orca imports hosts from your OpenSSH config files (SSH docs), so
wslmay already be listed. If it isn't, add it by hand: hostlocalhost, port2222, your WSL user. -
Identity file: the placeholder in this field shows a Linux-style path. That's only an example. Enter the Windows path to your private key, the file without
.pub:
C:\Users\<you>\.ssh\id_ed25519
The private key belongs to the side that starts the connection, and that's Orca on Windows. Because your config already points to this key, you can usually leave the field empty.
- Click Test. The first connection is slower because Orca sets up its server inside WSL.
- Add a project, choose the remote host option, pick
wsl, and enter a Linux path such as/home/<you>/repos/<repo>.
Step 4: Check that it works
If all six checks pass, Orca is running entirely inside WSL. The last one matters most, because file watching is the thing Option A was missing.
-
Test button: Settings β SSH β
wslβ Test reports a successful connection. -
Project path: the project opens from a
/home/...path. -
Terminal: open a terminal in the project and run the commands below. You should see a Linux path, a
microsoft-standard-WSL2kernel, and your WSL user.
pwd
uname -a
whoami
-
Git:
git statusanswers instantly and shows your branch. -
Agent: a Claude Code or Codex session starts without
command not found. -
File watching: run
touch test.txtin the terminal. The file should appear in Orca's file explorer within a second or two, without a refresh. Then runrm test.txt.
Troubleshooting
I hit the first two myself.
| Symptom | Cause | Fix |
|---|---|---|
connect to host localhost port 2222: Connection refused |
sshd is still on port 22 because of socket activation, or isn't running | Step 1.4, then check that sudo ss -tlnp lists sshd on :2222
|
Host key verification failed on first connect |
The trust prompt wasn't answered with yes
|
Run ssh wsl again and type yes
|
| Asks for a password |
authorized_keys is missing the key, or permissions are too open |
Redo Step 2.2, including both chmod lines |
ssh wsl fails with Bad configuration option or Could not resolve hostname wsl
|
config was saved as UTF-16 or as config.txt
|
Recreate it with -Encoding ascii (Step 2.3) |
Agent says command not found
|
The agent is only installed on Windows | Install it and log in inside WSL |
| Orca shows Disconnected after a while | WSL stopped the distro because nothing was using it | Open any WSL terminal to start it, then reconnect |
If the last row keeps happening, set up a Windows logon task that starts your distro, so it's running before Orca connects.
Wrapping up
Your repos stay in WSL, Orca runs on Windows, and SSH connects the two, so nothing has to read your code over the 9P bridge. It's one extra service to keep running, and for me it was worth it. If you try the \\wsl.localhost route and it holds up on your repos, tell me in the comments. I'd like to know how it compares.
Sources
- Orca docs: SSH worktrees
- Orca docs: Terminal
- Orca docs: Settings reference
- Orca PR #8287: WSL native project support
- Orca PR #30693: Git in WSL repos opened by UNC path
- Orca PR #34632: WSL background scans
- Orca PR #26678: false wsl-unavailable
- Docker docs: Connect Orca to a sandbox
- Windsurf: WSL performance and 9P
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.