# Windows and WSL

import { Callout } from "nextra/components";

Pane is a native Windows app. It isn't a port, and you don't need WSL to use it. But if your code lives in WSL, Pane works there too. Your agents run in the distro, with your Linux tools, and Pane stays a normal Windows window.

## Install on Windows

1. Download the `.exe` for your machine from [Download](/docs/download). There's an **x64** build and an **ARM64** build for Surface and other Snapdragon PCs.
2. Run the installer. You pick where it goes, and it adds Start menu and desktop shortcuts.
3. The installer isn't code-signed yet, so SmartScreen may warn you. Click **More info**, then **Run anyway**.

You need [Git for Windows](https://git-scm.com/download/win) and at least one agent CLI. Install the GitHub CLI (`gh`) too if you want PR status.

### Pick your shell

Pane auto-detects your shell and prefers Git Bash. Want something else? Open **Settings → Terminal → Windows shell** and pick Git Bash, PowerShell 7, Windows PowerShell or Command Prompt.

## Use a repo inside WSL

Keep the repo on the Linux side and add it to Pane by its WSL path:

1. Click the **+** icon in the sidebar, or press <KeyCombo keys={["Ctrl", "⇧", "N"]} />.
2. Pick the folder through `\\wsl$\` (or `\\wsl.localhost\`), for example `\\wsl$\Ubuntu\home\you\code\my-app`.
3. Create a pane like normal.

That's it. Pane sees the WSL path and does the rest:

- **Terminals and agents run in the distro.** Every tab in that pane opens a Linux shell, with your Linux `node`, `git`, `python` and agent CLIs.
- **Worktrees stay on the Linux filesystem.** By default Pane puts them in a `worktrees` folder inside the repo, so git stays fast.
- **Pane's variables come with you.** `PANE_PORT`, `PANE_WORKSPACE_PATH` and the others reach WSL shells too.
- **Pasted images land in the distro**, so an agent in WSL can read them.
- **File watching just works.** Pane raises WSL's inotify limits on startup so big repos don't run out of watches.

Install your agents inside the distro, not on Windows. Check that Pane can find one with `runpane agents doctor --agent claude` (or `--agent codex`).

## Agents in WSL

| Agent | Native Windows repo | WSL repo |
|-------|---------------------|----------|
| Claude Code | yes | yes |
| Codex | yes | yes |
| Cursor | no | yes |
| Any other CLI | yes | yes, runs in the distro |

Cursor's agent CLI doesn't run natively on Windows, so Pane only offers it for WSL repos. Keep the repo in WSL and install `cursor-agent` there.

### MCP and skills inside WSL

Pane registers its [MCP server](/docs/mcp) inside every WSL distro where you've saved a repo, for Claude Code, Codex and Cursor. It installs its agent skills there too. Agents in WSL get the same Pane tools as agents on Windows. They reach the Windows app through WSL interop, so you don't install anything extra.

## Run a Session in WSL

A [Session](/docs/sessions) can run its agent in a WSL distro:

1. Click **+** next to **Sessions**.
2. Under the agent picker, set **Run agent in** to your distro. Windows is the default.
3. Create the Session.

The Session remembers its distro after restarts. Its `runpane` commands still reach the Windows app, so it can manage every pane you have.

## Use WSL as a remote host

You can also run Pane's host inside WSL and connect to it with [Remote Pane](/docs/remote-daemon). Use that when you want agents to keep running somewhere you can reach from your phone.

## Known limits

<Callout type="warning">
  These are the rough edges today.
</Callout>

- **WSL needs its default setup.** Pane expects Windows drives at `/mnt/c` and WSL interop turned on. A custom `[automount] root` in `wsl.conf` isn't supported.
- **Usage tracking doesn't see WSL agents yet.** [Usage & Limits](/docs/usage) reads Claude Code and Codex logs on the Windows side only.
- **`runpane` isn't on PATH in plain WSL terminals.** Sessions get a wrapper automatically. In other WSL shells, call it through PowerShell: `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane doctor'`.
- **The Windows installer is unsigned**, so expect a SmartScreen prompt on install.

## Related

- [Download](/docs/download)
- [Custom agents](/docs/custom-agents): run any CLI, including in WSL
- [Troubleshooting](/docs/troubleshooting)