Windows via WSL2 is available as a preview in Onyx 0.1.20. The tested environment
is Windows 11 x64, WSL2 and Ubuntu 24.04 LTS, with Linux-local repositories and tools.
Real research, all three worker providers, installation, upgrade/rollback and
interruption recovery have passed on that environment. Fresh Windows/WSL login,
the browser callback, and the complete Windows Terminal /onyx journey remain
scheduled for follow-up testing. These checks are deferred, not certified.
Install inside Ubuntu
Install WSL2 and Ubuntu 24.04 using Microsoft’s
WSL installation guide.
In PowerShell, use wsl --list --verbose to confirm Ubuntu runs as version 2.
Open Ubuntu in Windows Terminal and use a normal Linux user.
Clone your repository into the distribution’s Linux home, such as ~/projects.
Keep the repository, common Git directory, Onyx config, provider installations and
evaluator working directories on Linux-local storage. /mnt/c, other Windows
mounts, network shares, and aliases or symlinks into them cannot be used for
protected Onyx operations. An externally located common Git directory is checked
separately. Linux-local temporary storage is permitted.
Run the existing installer from the Ubuntu shell:
It installs the Linux binaries, checks their checksums, offers PATH setup and
installs the packaged skill. Open a fresh Ubuntu terminal to verify PATH. The
compiled binaries do not require Bun; a provider or your evaluator may have its
own runtime dependencies. Reinstalling uses the same installer and preserves
profiles and pending research evidence.
Authenticate and install providers
Automatic login in WSL uses device authorization. Open the displayed verification
URL in your Windows browser and enter the code. Multi-team accounts choose a team
in the terminal. Explicit onyx login --device and onyx login --browser override
the default; browser mode requires a working loopback callback.
Credentials use Linux Secret Service when available and a private Linux file
fallback otherwise. Keep ONYX_HOME and XDG_CONFIG_HOME, if configured, inside
Linux. Unsafe storage blocks login before authorization and blocks token refresh
before rotating a token. Remote reads can continue with a usable unexpired
credential; they do not make unsafe storage acceptable for refresh.
Install Codex, Claude Code, or OpenCode using that provider’s Linux instructions,
and authenticate the provider separately from Onyx. Resolve git, your provider,
and onyx-worker inside Ubuntu. Onyx preflight rejects Windows executable files
and recognizable Windows installation shims, and verifies the pinned worker CLI.
Upgrade onyx and onyx-worker together. Keep the intended installation first on
the Linux shell’s PATH; a protocol mismatch blocks research before a session is
created. Preflight pins the resolved worker for the session.
Do not disable a provider’s sandbox to bypass a missing Linux prerequisite.
For OpenCode, choose an exact provider/model ID from opencode models with
onyx research run --model; confirm it uses the provider account you authenticated.
The main agent running /onyx must execute its commands in this same Linux
distribution, as must spawned workers. A Windows editor may view the Linux
checkout, but a Windows-hosted shell is not the research execution environment.
Windows-native executables and Windows-only evaluators are outside this target.
GPU, USB, physical hardware and proprietary evaluator compatibility depend on the
workload and require separate testing.
Stop and recover
Stop research before intentionally shutting down Ubuntu or Windows:
WSL termination and Windows restart interrupt Linux processes. Detached supervisors
are not a Windows service, and research sessions are never resumed. Keep the
launching Windows Terminal open while research runs. Survival after closing all
terminal windows or sleeping the host is not certified in this preview. After an
unexpected interruption, reconnect and use the recovery commands below.
Terminating a distribution can leave the Linux boot ID unchanged; restart alone
does not prove ownership or safe cleanup of recorded processes.
After an interruption:
Runtime recovery skips verified live supervisors, preserves terminal attempts and
immutable refs, and removes worktrees and credential runtime directories only when
process ownership permits cleanup. Uncertain process identity, unaccounted runtime
artifacts and unsupported evidence block cleanup. Inspect the returned reasons;
never delete the pending-report directory to clear an error. Repeat recovery after
resolving a blocker. --dry-run makes no local or remote changes.
Remote cleanup acknowledgement requires available credentials for the original
team and API origin. If delivery is blocked after safe local cleanup, retain the
receipts and retry recovery when authentication and connectivity are restored.
Runtime recovery leaves remote session cutoffs unchanged. If the session remains
open, use its explicit research stop --session <id> command. Starting research
again creates a new session. Plain research recover only retries bounded report
and cleanup-receipt delivery. A pending report may already be acknowledged but
still require an immutable-ref push.
Occupied resource slots never reset automatically. After verifying every launcher
and resource user is idle, inspect and use the existing reset procedure:
A crash while launch/recovery holds onyx-runtime-reconciliation can leave that
resource occupied too. Do not reset it while another launch or recovery is running.
Use research clean --dry-run before deleting idle runtime and logs; unresolved
execution and pending reports prevent cleaning.
Onyx 0.1.20 requires matching protocol-6 onyx and onyx-worker
binaries. Linux evaluators launched through Onyx have separate process-group
ownership records. If recovery reports uncertain evaluator ownership or an
interrupted launch, retain its runtime evidence and resolve the listed process
before retrying. Do not delete the runtime directory to bypass the blocker.
Networking
Verify API HTTPS access, Git authentication and provider access from Ubuntu.
Corporate proxies, VPNs and certificate stores can differ between Windows and
Linux. Configure the Linux tools’ supported proxy/CA settings. Device authorization
avoids relying on browser opening and loopback forwarding across environments.
Forced browser login additionally needs Windows-to-WSL localhost connectivity;
see Microsoft’s WSL networking guide.
Onyx does not change WSL mounts, interoperability, global PATH, firewall settings,
or memory limits automatically.
Preview qualification
The initial candidate passed the required source/compiled research matrix, including
Codex 0.145.0, Claude Code 2.1.263 and OpenCode 1.17.11 with
opencode/claude-sonnet-4-6. Each provider canary produced four successful measured
edits and verified immutable refs. The host used Windows 11 Home 23H2 build
22631.4460, WSL 2.7.13.0, Ubuntu 24.04.4 and Git 2.43.0. This is a narrow tested
configuration, not a claim about every Windows/WSL/provider version.
Fresh authentication and refresh/revocation on this Windows environment, authenticated
profile preservation across upgrades, explicit browser callbacks, Terminal UI and
lifetime, and the full main-thread /onyx journey remain follow-up work. Longer
sleep/network failures and wider compatibility matrices are also deferred.
