From a5f039590de131f1467a7d08e18f9003e1dcdf3e Mon Sep 17 00:00:00 2001 From: Mike Schwarz <171890339+mvschwarz@users.noreply.github.com> Date: Wed, 7 Oct 2026 13:22:49 -0700 Subject: [PATCH] docs: add a user's reported WSL2 setup to the getting-started guide (#960) The getting-started guide records WSL2 as one user's reported working setup, not a supported platform. --- README.md | 3 ++- docs/reference/getting-started.md | 27 ++++++++++++++++++++++++++- docs/reference/help.md | 3 ++- 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d59a857cb..07d0e3d08 100644 --- a/README.md +++ b/README.md @@ -420,7 +420,8 @@ seat, plugin, and release lifecycle actions remain agent-owned. longer supported. Node 26 and other versions are untested. On a Mac with Apple silicon, use Node.js 22: see the [compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation). - tmux -- macOS or Linux. Native Windows is not supported yet, and WSL2 has not been tested +- macOS or Linux. Native Windows is not supported yet. WSL2 isn't supported either; + one user's working setup is in the [getting-started guide](docs/reference/getting-started.md#wsl2-a-reported-working-setup) Optional: - herdr or cmux for terminal workspaces showing the agents together diff --git a/docs/reference/getting-started.md b/docs/reference/getting-started.md index b5ab58bb1..be325032d 100644 --- a/docs/reference/getting-started.md +++ b/docs/reference/getting-started.md @@ -22,7 +22,8 @@ supported version with [nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`) or NodeSource. On a Mac with Apple silicon, use Node.js 22 (see the [compatibility history](../releases/v0.5.15.md#known-compatibility-limitation)). Native -Windows is not supported yet, and WSL2 has not been tested. Node 20 and +Windows is not supported yet. WSL2 isn't a supported platform either, though one +user has [reported a working setup](#wsl2-a-reported-working-setup). Node 20 and odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later even-numbered releases are untested. @@ -62,6 +63,30 @@ before-install view explain that access before you choose it. > "kernel ready" does not mean every kernel agent is healthy; a workspace root > being *live* does not mean it is the *right* one for your project. +## WSL2: a reported working setup + +This is one user's report, not a supported platform. +[dajiaohuang](https://github.com/dajiaohuang) +[ran OpenRig 0.6.6 under WSL2](https://github.com/mvschwarz/openrig/issues/88#issuecomment-6043925546) +on Ubuntu 24.04, with Node.js 24.14.1, tmux 3.4, Codex CLI 0.161.0 and Pi +(`@earendil-works/pi-coding-agent`) 1.0.4, headless, as the distribution's root +user. + +- **What worked**, with one Codex seat and one Pi seat: `rig doctor`, starting + the daemon (`rig daemon start --no-kernel`), launching both seats, replies to + `rig send` and `rig capture`, and stopping with `rig down --snapshot` + followed by a warm restore with `rig up --existing`. +- **What mattered:** + - the install and the OpenRig instance on the Linux filesystem; + - Linux-native Node.js and harnesses, not the Windows `npm` or `pi` that WSL + inherits; + - Pi credentials in the managed seat's agent directory, because a global Pi + login isn't shared with managed seats; + - the current `@earendil-works/pi-coding-agent` package in its own npm prefix, + not the deprecated `@mariozechner` one. +- **Not tested:** the kernel and operator, herdr, reboot, suspend and resume, + cross-host operation and long-running work. + ## Install and sign in **One command, when the person wants the full setup.** It needs Node.js 22 or 24 with npm already installed. First diff --git a/docs/reference/help.md b/docs/reference/help.md index ff701ab45..88005a0c5 100644 --- a/docs/reference/help.md +++ b/docs/reference/help.md @@ -47,7 +47,8 @@ rather than treating a newer command as installed. ### Installation or platform problems -Supported platforms are macOS and Linux. Native Windows is not supported yet, and WSL2 has not been tested. OpenRig needs +Supported platforms are macOS and Linux. Native Windows is not supported yet. WSL2 isn't supported either; one user's +[reported working setup](getting-started.md#wsl2-a-reported-working-setup) lists what mattered. OpenRig needs Node.js 22 or 24 and tmux. A Linux distribution's own Node.js can be older; check `node --version`. With npm 11 or later, an `npm warn install-scripts` line for `@openrig/cli` means only the postinstall Node.js and SQLite check was skipped; `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"` runs it. A WSL error needs its actual versions,