# @akms/mcp-wsl

> 🔒 Internal use only — built for our organization's services.

MCP server that lets an AI agent run shell commands and transfer files in a WSL distro **on this machine**, through `wsl.exe`.

No sshd in the distro, no key, no port, no networking mode to keep alive: the first call starts the distro if it is stopped, and the Linux user is one variable. The distro is **pre-registered** in the server's own environment; the agent never names a distro or a user, and no tool takes one. Every command and path is screened by the [`@akms/mcp-ssh`](https://www.npmjs.com/package/@akms/mcp-ssh) guard policy plus the rules that only a WSL host needs.

Windows only — the transport is `wsl.exe`. For reaching a WSL distro from *another* machine, keep using `@akms/mcp-ssh` against its sshd.

## 📦 Installation

Run these commands from Windows PowerShell with Node.js and npm installed. The target distro must already be registered with WSL and have `bash` available; `config` registers MCP entries, not new WSL installations.

```powershell
npm install -g @akms/mcp-wsl   # installs the `akms-mcp-wsl` command
npx -y @akms/mcp-wsl --help    # or run it straight from the registry
wsl -l -v                    # list the installed distros
```

## ⚙️ MCP client setup

**Let the CLI write it.** `config` opens a small manager for the distros registered in a client's config. No `WSL_*` name has to be remembered.

```powershell
npx -y @akms/mcp-wsl config                   # opens on the first client found on this machine
npx -y @akms/mcp-wsl config --target codex    # claude-code | codex | claude-desktop | cursor
```

```
Claude Code (user scope)  C:\Users\me\.claude.json

? 2 WSL entries — pick one to manage it
❯ wsl_ubuntu_root    root@Ubuntu
  wsl_ubuntu_deploy  deploy@Ubuntu  readonly, paths /var/log,/opt/app
  ────────────────────────
  Add a distro
  Switch client  also found: Codex CLI
  Quit
↑↓ move · enter select · esc back
```

The entries are the menu: pick one to edit, check, print or remove it. Adding or editing opens a settings form — every setting listed with its value, picked and changed in any order, with **Test the distro** and **Save** below:

```
? New distro entry
❯ Distro          Ubuntu
  User            distro default  the Linux user commands run as
  Server name     wsl_ubuntu      follows the distro and user until you change it
  Description     none            shown to the agent
  Read-only       no              enter toggles
  Windows access  locked          enter toggles · .exe through interop, writes under /mnt/<drive>/
  File paths      anywhere        where the file tools may read and write
  ────────────────────────
  Test the distro  runs 'id' as the user · starts a stopped distro
  Save             to Claude Code (user scope)
  Cancel
```

The distro is picked from what `wsl -l -v` lists, and a new entry starts on the default one. Test runs the same check as `--check`; Save offers it when the values changed since the last one. Esc always goes back one level — out of a field with the value unchanged, from the write preview back into the form. Where the terminal cannot send arrow keys (a pipe, Git Bash's mintty), the same lists are numbered and answered by number.

Starting in **0.1.2**, `config` is the only configuration command. Update scripts and shortcuts to use `akms-mcp-wsl config`; `--target` works as before. The former `setup` command exits with code 1 and a reminder to use `config`.

| Client | Config file | How it is written |
|---|---|---|
| Claude Code | `~/.claude.json` (user scope) | through `claude mcp add-json … -s user`, never by editing the file |
| Codex | `~/.codex/config.toml` | only the `[mcp_servers.<name>]` tables are rewritten; keys you added to them stay |
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` | `mcpServers.<name>` is set, every other key kept |
| Cursor | `~/.cursor/mcp.json` | same |

Only entries that launch this package are listed or touched — `@akms/mcp-ssh` entries in the same file are left alone. An edit keeps every `WSL_*` variable the form does not show (`WSL_CWD`, `WSL_ALLOW_SUDO`, allow-lists, timeouts, …). **Print** shows an entry as JSON, as a Codex TOML table and as a `claude mcp add-json` line, for when pasting is easier. Entries launch through `cmd /c npx`, the form Claude Code expects for npx servers on Windows.

**Or by hand — one server entry per distro and user** — plain `WSL_*` variables in the MCP client's config, with no separate server config file. Claude Code reads `.mcp.json` in the project or `~/.claude.json` globally; Claude Desktop takes the same block inside `claude_desktop_config.json`. Use `cmd /c npx`, matching the entries generated by `config`:

```json
{
    "mcpServers": {
        "wsl_ubuntu_root": {
            "command": "cmd",
            "args": ["/c", "npx", "-y", "@akms/mcp-wsl"],
            "env": { "WSL_DISTRO": "Ubuntu", "WSL_USER": "root", "WSL_DESCRIPTION": "nginx, cloudflared and the test stack" }
        },
        "wsl_ubuntu_deploy": {
            "command": "cmd",
            "args": ["/c", "npx", "-y", "@akms/mcp-wsl"],
            "env": { "WSL_DISTRO": "Ubuntu", "WSL_USER": "deploy", "WSL_READONLY": "true", "WSL_ALLOWED_PATHS": "/var/log,/opt/app" }
        }
    }
}
```

`WSL_DISTRO` is the whole minimum (the name as `wsl -l -q` prints it). Because each server fronts one distro *as one user*, the agent never picks either: `wsl_exec({ command: "df -h" })` is a complete call, and root access is a matter of which entry exists — not of an argument. The server name is what the agent sees in its tool list, so put the user in it.

The server speaks MCP over **stdio**: stdout carries the JSON-RPC stream and all logging goes to stderr. When the client goes away — stdin ends, or the process is simply gone — the server exits within a few seconds on its own; a stderr nobody reads is never a reason to stay. Its log says `mcp server ready on stdio` with its `pid`, for when one has to be found among a client's processes.

## 🗂️ Distro configuration

| `WSL_*` variable | Description |
|---|---|
| `WSL_DISTRO` ✅ | Distro name as `wsl -l -q` prints it. Required by name — following `wsl --set-default` would let a machine-wide setting silently redirect every command |
| `WSL_USER` | Linux user (`wsl -u`). The distro's default user when unset |
| `WSL_NAME` | Alias shown to the agent; defaults to the distro name |
| `WSL_DESCRIPTION` | Shown to the agent — say what the distro is for |
| `WSL_CWD` | Directory new sessions start in |

### Policy

| `WSL_*` variable | Default | Effect |
|---|---|---|
| `WSL_READONLY` | `false` | Rejects write commands, output redirection, package installs, uploads and writes |
| `WSL_ALLOW_SUDO` | `true` | When false, rejects `sudo` / `su` / `doas` / `pkexec` / `runuser` / `chroot` |
| `WSL_ALLOW_WINDOWS` | **`false`** | When false, rejects Windows interop executables (`powershell.exe`, `cmd.exe`, any `.exe`) and **writes** whose target is under `/mnt/<drive>/`. Reads and copies *out of* `/mnt` are always allowed |
| `WSL_ALLOW_COMMANDS` | *(none)* | When set, only these binaries may run (`pwd` is added automatically so sessions can open) |
| `WSL_DENY_PATTERNS` | *(none)* | Extra regex sources, compiled at startup and tested per command segment |
| `WSL_ALLOWED_PATHS` | *(none)* | When set, the file tools accept only absolute paths inside these prefixes |
| `WSL_EXEC_TIMEOUT_MS` | `60000` | Per-command wall clock; `wsl.exe` is killed when it elapses |
| `WSL_MAX_OUTPUT` | `100000` | stdout and stderr are each truncated past this |
| `WSL_MAX_READ_BYTES` | `200000` | `wsl_read_file` ceiling |

The stance is `@akms/mcp-ssh`'s: **permissive by default**, restriction opt-in, and a malformed value fails startup (`WSL_READONLY=ture` is an error, not "not read-only"). The one default that differs is `WSL_ALLOW_WINDOWS`, and the reason is in the security notes below.

### Check it before wiring it up

`--check` reads the current process's `WSL_*` environment, not the MCP client's saved entries. Set the variables in the same PowerShell session, using an installed distro and Linux user:

```powershell
$env:WSL_DISTRO = "Ubuntu"
$env:WSL_USER = "root"        # optional; omit to use the distro's default user
akms-mcp-wsl --check          # or: npx -y @akms/mcp-wsl --check
```

```
Checking Ubuntu  →  root@Ubuntu

  OK      uid=0(root) gid=0(root) groups=0(root)  (115ms)
          distro: Running  ·  WSL 2  ·  networking mirrored  ·  systemd  ·  kernel 5.15.146.1-microsoft-standard-WSL2
```

To check a saved entry, open `config`, select the entry, then **Check the distro**. Both checks run `id` as the configured user and can start a stopped distro. If `WSL_ALLOW_COMMANDS` is set, include `id` for the check to pass. `--check` exits with code `0` on success and `1` on failure.

## 🧰 Tools

| Tool | Purpose |
|---|---|
| `wsl_list_hosts` | The configured distro and user, the guard policy, and the distro's state: running/stopped, WSL version, networking mode, whether systemd is PID 1 |
| `wsl_connect` | Open a session (a remembered working directory), returns a session id |
| `wsl_disconnect` | Forget a session |
| `wsl_list_sessions` | Open sessions with cwd, command count and idle time |
| `wsl_exec` | Run a command in a login bash; returns stdout, stderr, exit code, duration |
| `wsl_list_dir` | Directory listing (type, mode, size, mtime) |
| `wsl_read_file` | Read a text file, truncated to the byte ceiling |
| `wsl_write_file` | Write or append UTF-8 text |
| `wsl_upload` | Local → distro file transfer |
| `wsl_download` | Distro → local file transfer |

### Every call is its own process

There is no connection to keep. Each tool call spawns `wsl.exe -d <distro> -u <user> --exec bash -lc <script>` and waits for it — about 100 ms of overhead, no handshake. A **session** therefore carries exactly one thing between calls: the working directory, so `cd /opt/app` in one `wsl_exec` still applies to the next. Environment variables, background jobs and `sudo` timestamps do not carry over, because the process that held them has exited.

`--exec`, never `--`: with `--`, `wsl.exe` hands the command to the distro's default shell for a *second* parse, which strips backslashes and expands `$HOME` before bash ever sees the script — the text the guard screened would not be the text that runs.

### Commands run without a terminal

stdin is closed, so anything that waits for input fails fast instead of hanging until the timeout: `sudo` without `NOPASSWD` fails with `a password is required`, prompts need their non-interactive flag (`apt-get -y`), full-screen tools have no TTY (`top -bn1`, `wsl_write_file` instead of an editor).

**A background job must detach all three descriptors**, or `wsl.exe` waits on the open pipe until the timeout kills it:

```bash
nohup ./build.sh > /tmp/build.log 2>&1 < /dev/null &
```

When the timeout fires, `wsl.exe` is killed; the process inside the distro may survive. The reply says so.

### File tools go through the distro process

`wsl_read_file` is `head -c`, `wsl_write_file` is `cat >`, transfers are `cat` over stdin/stdout — byte-clean pipes, so binaries round-trip intact. This is deliberate: the `\\wsl$\` share opens every file as the distro's *default* user, so a `root` entry could not have written `/etc/nginx/…` through it. Through the process, the registered user's permissions are the permissions.

These scripts have no variable part but the quoted path, so they bypass the command guard the way SFTP does in `@akms/mcp-ssh`; the **path** guard (`WSL_ALLOWED_PATHS`, read-only, the `/mnt` rules) governs them instead. `WSL_ALLOW_COMMANDS` need not list `cat` or `find`.

## 🛡️ Guard policy

The command guard is `@akms/mcp-ssh`'s, unchanged — catastrophe rules always on (`rm -rf /`, `mkfs`, `dd of=/dev/sda`, `shutdown`, fork bombs…), the rest opt-in. Its threat model is a **mistaken agent, not an adversary**, and so is this server's. On top:

| Layer | Scope | Examples |
|---|---|---|
| **WSL catastrophe** | Always | `wsl --shutdown` / `--terminate` / `--unregister`, `wslconfig /t`, `poweroff`, `systemctl poweroff`, `init 0` |
| `WSL_ALLOW_WINDOWS=false` | Default | any segment whose binary is a Windows executable (`powershell.exe`, `cmd.exe`, `explorer.exe`, `*.exe`); any write-shaped segment whose **target** is under `/mnt/<drive>/` — a redirection, `cp`'s last operand, `tar -c`'s archive, `rm`/`sed -i`/`mv` operands |
| **Operator paths** | Always, even when Windows is open | `/mnt/c/Users/<you>/.ssh`, `.aws`, `.gnupg`, `*.pem`, `.claude.json`, `.mcp.json`, `claude_desktop_config.json` — the same list `@akms/mcp-ssh` protects on the local side, reached through the mount |

Both `wsl_exec` and the file tools enforce these; the rules live in the layer every command and path passes through, so a new tool cannot forget them. A rejection returns the rule that fired, the offending segment, and the note that nothing was run.

## ⚠️ Security notes

**In WSL, the "remote" is your own machine.** `@akms/mcp-ssh` can say "the remote account is the real boundary" because a compromised remote account stays remote. Here the distro shares the Windows filesystem under `/mnt` and can launch Windows programs through interop — and among the files it can reach that way is the MCP client configuration that defines this server's own `WSL_*` policy. An agent that writes `~/.claude.json` rewrites its guards for the next run. That is why `WSL_ALLOW_WINDOWS` is the one restriction on by default, and why the operator's credential and configuration paths stay refused even when it is turned on.

- Prefer a dedicated Linux user per entry over `root`, with `sudoers` scoped to what it needs — the guard is a seatbelt, the account is the containment.
- The catastrophe rules read the command as text. A shell can express the same operation in unlimited ways; the guard stops mistakes, not intent.
- Output from the distro is untrusted input: a file the agent reads can contain instructions.
- Local paths in `wsl_upload` / `wsl_download` are resolved on Windows, so a POSIX-looking `/tmp/x` becomes `<current drive>\tmp\x`. Every transfer reply prints the resolved path — check it.

## 📄 Logging

Everything goes to **stderr**. `WSL_MCP_LOG_LEVEL` picks the level — `silent` / `debug` / `info` / `warn` / `error`, default `info`. Guard rejections are logged at `warn` with the full command; full command text is otherwise only logged at `debug`.

## 🧑‍💻 Development

Building on this server, embedding it as a library, or changing the guards — see [README_DEV.md](README_DEV.md).

## 📜 License

MIT — see [LICENSE.md](LICENSE.md).