deepscientist-windows-wsl-setup

name	deepscientist-windows-wsl-setup
description	Install, repair, and validate DeepScientist on Windows with WSL2 until the Windows browser can open the DeepScientist Web UI. Use when an agent needs to set up or fix DeepScientist on a Windows machine, including WSL distro creation, Linux-side Node/Python prerequisites, Codex auth/relay configuration, WSL proxy troubleshooting, and final `ds doctor` or Web UI verification.

DeepScientist Windows WSL Setup

One-liner for humans

Copy this to any AI coding agent (Claude Code, Codex, Cursor, etc.) to trigger the install:

Install DeepScientist on this Windows machine using WSL2. Follow the skill at deepscientist-windows-wsl-setup/SKILL.md in the DeepScientist repo for the full procedure. Keep going until ds doctor passes and I can open http://127.0.0.1:20999 in my Windows browser.

Workflow

1. Read the current official DeepScientist README and Windows WSL2 deployment guide before changing anything. Use the official repo as the source of truth for install commands and note any version pins or prerequisites that changed.
2. Inspect the machine first:
   • wsl -l -v
   • wsl --status
   • Check whether a usable WSL2 Ubuntu distro already exists.
   • Check whether Linux-side node, npm, git, uv, codex, and ds already exist inside the target distro.
3. Prefer a dedicated WSL2 Ubuntu distro for DeepScientist instead of modifying docker-desktop or converting an unrelated user distro unless the user asks for that explicitly.
4. Keep working until these end-state checks pass:
   • Linux-side codex exec --skip-git-repo-check "Print exactly OK and exit." succeeds.
   • ds doctor reports [ok] Codex CLI (or [warn] Codex CLI: Codex startup probe completed.).
   • ds starts and Windows can open http://127.0.0.1:20999.

Human actions required

Some steps require the human to act. The agent cannot do these:

When	What the human must do
WSL cannot start (HCS_E_CONNECTION_TIMEOUT)	Reboot the PC. Pending Windows updates or long uptimes cause Hyper-V VM creation to fail.
Proxy listens only on 127.0.0.1	Open the proxy app (Clash, v2rayN, etc.) and enable Allow LAN so it listens on 0.0.0.0.
No valid OpenAI auth	Either (a) run codex login in a GUI terminal, or (b) provide an API key or relay config.
ChatGPT subscription expired	Renew subscription, or provide a third-party API relay endpoint and key.
Firewall blocks WSL networking	Temporarily allow WSL/Hyper-V through Windows Firewall.

Pre-flight checks (critical)

HCS_E_CONNECTION_TIMEOUT

If wsl -d <distro> -- echo hello fails with HCS_E_CONNECTION_TIMEOUT:

1. Check pending reboot: look at HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager for PendingFileRenameOperations.
2. Check uptime: (Get-CimInstance Win32_OperatingSystem).LastBootUpTime. If > 7 days, suggest reboot.
3. Try wsl --shutdown then retry. If it still fails, a reboot is required.
4. Do not proceed with installation until WSL can start.

Available memory

If free memory < 2 GB, warn the user. WSL2 VM needs at least 1 GB to start reliably. Check with:

$mem = Get-CimInstance Win32_OperatingSystem
[math]::Round($mem.FreePhysicalMemory/1MB,2)

Distro setup

• If no suitable WSL2 Ubuntu distro exists, install one with a dedicated name such as DeepScientist.
• Prefer Ubuntu 22.04 or 24.04 unless the official guide says otherwise.
• If the user already has a broken WSL1 distro, do not repurpose it by default. Create a new WSL2 distro and leave the old one alone.
• After installation, create a normal Linux user such as ds and make it the default user for that distro.
• Disable Windows PATH injection in the DeepScientist distro to avoid accidentally using Windows-side npm, codex, or other binaries:

printf '[interop]\nappendWindowsPath=false\n' | sudo tee /etc/wsl.conf

• Restart that distro after changing /etc/wsl.conf with wsl --terminate <distro>.
• After restart, verify that command -v node does NOT resolve to /mnt/c/....

Linux prerequisites

Install the Linux-side dependencies inside the target distro. Prefer native Linux binaries over Windows binaries mounted under /mnt/c or other drives.

Required baseline (adapt the python3-venv package name to the distro version):

sudo apt-get update
# Ubuntu 24.04:
sudo apt-get install -y ca-certificates curl gnupg git sudo build-essential python3-venv python3-pip
# Ubuntu 22.04:
sudo apt-get install -y ca-certificates curl gnupg git sudo build-essential python3.10-venv python3-pip

Install Node.js 20 unless the official guide says otherwise:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
printf 'deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main\n' | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install -y nodejs

Set a user-local npm prefix so global packages do not require sudo:

mkdir -p "$HOME/.npm-global" "$HOME/.local/bin"
npm config set prefix "$HOME/.npm-global"

Add to both ~/.bashrc and ~/.profile:

export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:$PATH"

DeepScientist installation

• Install the current official DeepScientist package from npm.
• Install uv.
• Install the Codex CLI version required by the official DeepScientist guide. If the guide pins a specific version, follow the guide instead of guessing.

Typical pattern:

npm install -g @researai/deepscientist
npm install -g @openai/codex@0.57.0
curl -LsSf https://github.com/astral-sh/uv/releases/latest/download/uv-installer.sh | sh

After installation, verify Linux-side resolution:

command -v ds
command -v codex
command -v uv

All three must resolve to Linux paths (under $HOME/.npm-global/bin or $HOME/.local/bin), NOT under /mnt/c/.

Codex auth and API relay

Option A: Reuse Windows-side ChatGPT auth

If WSL cannot complete browser-based Codex login, reuse the Windows-side auth file:

1. Inspect whether Windows already has a working auth file at C:\Users\<user>\.codex\auth.json.
2. Back up any existing Linux auth file first.
3. Copy the Windows auth file into ~/.codex/auth.json.
4. Run chmod 600 ~/.codex/auth.json.

Caveat: If the ChatGPT subscription is expired, auth will copy successfully but codex exec will fail with model errors. Check chatgpt_subscription_active_until in the JWT token.

Option B: Third-party API relay (common in China)

Many users in China use third-party API relay services instead of direct OpenAI access. If the user provides a relay endpoint and API key, configure:

~/.codex/config.toml:

model_provider = "OpenAI"
model = "<model-from-relay>"
review_model = "<model-from-relay>"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "<relay-base-url>"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

[features]
responses_websockets_v2 = true

~/.codex/auth.json:

{
  "OPENAI_API_KEY": "<relay-api-key>"
}

Known gotcha: Codex 0.57.0 does not accept model_reasoning_effort = "xhigh". Valid values are: minimal, low, medium, high. If the relay template says xhigh, change it to high.

Option C: Direct OpenAI API key

If the user has a platform.openai.com API key:

~/.codex/auth.json:

{
  "OPENAI_API_KEY": "sk-..."
}

No config.toml changes needed for the base URL in this case.

Proxy and NAT repair

First determine whether the user is using a Windows-side local proxy at all. Do not assume every machine needs proxy handling.

Quick connectivity test (run this early to decide if proxy is needed):

curl -s --max-time 10 -o /dev/null -w '%{http_code}' https://chatgpt.com/
curl -s --max-time 10 -o /dev/null -w '%{http_code}' https://github.com/

If both return 200 or 3xx, proxy may not be needed. If chatgpt.com returns 000 (timeout/reset), proxy is almost certainly needed (common in China).

Proxy detection rules

• Start by asking or inferring three things: whether proxy is enabled, which proxy app is in use, and which local port the user expects.
• If those cannot be confirmed with high confidence from the machine state, stop and ask the user before writing proxy configuration.
• Treat app-specific defaults only as candidates, not facts. Common local proxy ports include 7890, 1080, 10808, 10809, and 20170, but users often customize them.
• Inspect whether the Windows proxy listens only on 127.0.0.1.
• If it does, ask the user to enable LAN access or equivalent so the proxy listens on a non-loopback address. This is a human action.
• Prefer the WSL gateway IP from ip route inside Linux over /etc/resolv.conf nameserver.
• Test the candidate proxy address from WSL before persisting it.

Use the bundled helper script for the Windows-side inspection:

pwsh -File scripts/find-wsl-proxy.ps1

If the user already told you the port, pass it explicitly:

pwsh -File scripts/find-wsl-proxy.ps1 -Ports 7890

Bash variable escaping in WSL commands

When running WSL commands from Windows (via wsl -d Ubuntu -- bash -c "..."), bash variable $ signs get consumed by the calling shell. Two reliable workarounds:

1. Write a .sh script to a temp file and run wsl -d Ubuntu -- bash /mnt/c/Users/<user>/AppData/Local/Temp/script.sh
2. Use a PowerShell wrapper: write a .ps1 file containing wsl.exe -d Ubuntu -- bash /path/to/script.sh and execute it via powershell.exe -ExecutionPolicy Bypass -File script.ps1

The PowerShell wrapper approach is the most reliable for avoiding escaping issues.

Persist proxy env

Only after the proxy port is confirmed:

cat > "$HOME/.wsl-proxy-env" <<'EOF'
host_ip="$(ip route 2>/dev/null | awk '/^default/ { print $3; exit }')"
proxy_port="<confirmed-port>"
if [ -n "$host_ip" ]; then
    export http_proxy="http://$host_ip:$proxy_port"
    export https_proxy="http://$host_ip:$proxy_port"
    export HTTP_PROXY="$http_proxy"
    export HTTPS_PROXY="$https_proxy"
    export ALL_PROXY="$http_proxy"
fi
EOF

Then source that file from both ~/.profile and ~/.bashrc:

echo '[ -f "$HOME/.wsl-proxy-env" ] && source "$HOME/.wsl-proxy-env"' >> ~/.bashrc
echo '[ -f "$HOME/.wsl-proxy-env" ] && source "$HOME/.wsl-proxy-env"' >> ~/.profile

Ignore the generic WSL warning about localhost proxy mirroring if:

• the distro has a working non-localhost proxy configuration, and
• codex exec and ds doctor both pass.

Validation

Run validation in this order:

1. Verify shell path and binaries:

whoami
command -v node npm git ds codex uv

2. Verify Codex can actually execute:

cd /tmp
codex exec --skip-git-repo-check "Print exactly OK and exit."

3. Verify DeepScientist:

ds doctor

4. Set git user info if ds doctor warns about it:

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

5. Start DeepScientist:

ds

6. Confirm Windows can reach the UI:

http://127.0.0.1:20999

Important: When starting ds from an agent, the process must outlive the agent's shell. Either:

• Start it in a separate WSL terminal window: Start-Process wsl.exe -ArgumentList '-d','Ubuntu','--','bash','-lc','ds'
• Or create a .bat shortcut on the Desktop for the user to double-click.

Troubleshooting

WSL won't start

• HCS_E_CONNECTION_TIMEOUT: Reboot required. Check pending reboot registry and uptime.
• LxssManager stopped and won't start: Reboot required. Service may be blocked by pending OS updates.
• If wsl shows a target distro as version 1, do not install into it until WSL2 is available or a new WSL2 distro is created.

Binaries resolve to Windows paths

• If command -v ds or command -v codex resolves under /mnt/c, fix PATH and disable Windows PATH injection before continuing.
• After editing /etc/wsl.conf, you must wsl --terminate <distro> for changes to take effect.

Codex model errors

• model is not supported when using Codex with a ChatGPT account: ChatGPT subscription expired or model not available on the plan. Switch to API relay.
• unknown variant xhigh: Codex 0.57.0 only supports minimal, low, medium, high. Change to high.
• Reconnecting... 5/5 then failure: usually a network issue. Check proxy first, then auth.

Proxy issues

• If you cannot reliably determine whether proxy is enabled or which port is correct, ask the user directly before editing shell proxy config.
• If codex exec fails with TLS resets or websocket resets, suspect proxy reachability before suspecting auth.
• If the copied auth file exists but ds doctor still says Codex startup probe failed, re-test network reachability to chatgpt.com and the proxy endpoint.

Python package issues

• python3.10-venv does not exist on Ubuntu 24.04. Use python3-venv instead. Always check lsb_release -r first.
• The first ds doctor run may take 10+ minutes as it downloads and installs the Python runtime via uv.

Other

• If ds says Codex is not marked ready yet. Running startup probe.., treat that as a normal transitional state until proven otherwise.
• If shell startup files were edited from Windows and start throwing syntax errors, normalize them back to LF line endings before debugging anything else.

Desktop shortcut

Create a .bat file on the Desktop for the user to launch DS easily:

@echo off
start wsl.exe -d Ubuntu -- bash -lc "ds; exec bash"
timeout /t 5 /nobreak >nul
start "" "http://127.0.0.1:20999"

References

• Read references/deepscientist-windows-wsl-notes.md for the concrete repair commands, common failure patterns, and the proxy/auth decision tree.