nexu-io__open-design/docs/wsl-setup.md

WSL2 Setup Guide

Use this guide when your coding-agent CLIs run inside WSL2. In that setup, install and run OpenDesign from WSL as well so the agent CLI, od command, daemon, Node modules, and credentials all come from the same Linux environment.

For native Windows PowerShell setup, use docs/windows-troubleshooting.md instead.

Recommended shape

• Clone OpenDesign inside WSL2.
• Install Node ~24 and the repo-pinned pnpm (10.33.2) inside WSL2.
• Put a WSL-native od wrapper before /usr/bin on PATH.
• Start the daemon from WSL with od --no-open.
• Install MCP entries from the same WSL shell.

Do not assume the Windows desktop app's daemon is the right daemon for WSL agent clients. WSL2 networking and Windows credential stores can make that path ambiguous. A WSL-started daemon keeps the MCP clients and OpenDesign in the same environment.

1. Install from source in WSL

git clone https://github.com/nexu-io/open-design.git ~/tools/open-design
cd ~/tools/open-design

node --version   # should print v24.x.x
corepack enable
corepack pnpm --version   # should print 10.33.2
pnpm install

If you use mise, trust and install the repo toolchain before pnpm install:

mise trust
mise install

2. Fix the od command collision

Linux already ships /usr/bin/od (octal dump). If that binary wins on PATH, commands such as od mcp install claude fail with file-not-found messages for mcp, install, and the agent name.

Check what your shell resolves:

type -a od

If /usr/bin/od appears before OpenDesign, create a wrapper in ~/.local/bin and make sure that directory is first on PATH:

mkdir -p ~/.local/bin

cat > ~/.local/bin/od <<'EOF'
#!/usr/bin/env bash
repo="$HOME/tools/open-design"
cd "$repo" || exit 127

if command -v mise >/dev/null 2>&1; then
  exec mise exec -- pnpm exec od "$@"
fi

exec corepack pnpm exec od "$@"
EOF

chmod +x ~/.local/bin/od
export PATH="$HOME/.local/bin:$PATH"
hash -r
type -a od

Expected first result:

od is /home/<user>/.local/bin/od

od.exe is not a reliable workaround from WSL. It may resolve to a Windows coreutils binary instead of OpenDesign, especially on machines with Windows coreutils installed.

3. Start the daemon from WSL

Run the daemon from the same WSL environment that your agent CLIs use:

cd ~/tools/open-design
od --no-open

In another WSL terminal, verify it is reachable:

curl -sSf http://127.0.0.1:7456/api/health && echo "OpenDesign daemon is reachable"

Expected output includes {"ok":true,...} followed by the echo line.

Do not probe the root URL (curl http://127.0.0.1:7456) for this check. The root path serves the web UI only after the web package has been built, so on a fresh source install it returns 404 even though the daemon is healthy. The MCP integrations below do not need the web build. If you also want the browser UI at http://127.0.0.1:7456, build it once and restart the daemon:

cd ~/tools/open-design
pnpm --filter @open-design/web build

Leave the daemon terminal running while using MCP integrations.

4. Install MCP entries

From WSL, run the installer for each agent CLI you use:

od mcp install claude
od mcp install opencode
od mcp install codex
od mcp install antigravity
od mcp install copilot

The installer writes to the agent config locations for the current WSL user, for example ~/.claude.json, ~/.config/opencode/opencode.json, ~/.codex/config.toml, ~/.gemini/antigravity/mcp_config.json, and ~/.copilot/mcp-config.json.

Native module mismatch after changing Node versions

If dependencies were installed under Node 22 and OpenDesign later runs under Node 24, native modules such as better-sqlite3 can fail with a NODE_MODULE_VERSION mismatch.

Reinstall under the active Node 24 runtime:

cd ~/tools/open-design
rm -rf node_modules
pnpm store prune
pnpm install

Then verify the native module loads:

pnpm --filter @open-design/daemon exec node -e "require('better-sqlite3')"

Codex config parse failures

If Codex fails before MCP install or a direct codex run with:

invalid type: map, expected a boolean
in `features`

check ~/.codex/config.toml for nested feature tables such as:

[features.multi_agent_v2]
hide_spawn_agent_metadata = false
max_concurrent_threads_per_session = 10000
enabled = false

Current Codex CLI versions expect [features] values to be booleans. Remove or comment out the nested [features.*] block, then retry the command.

OpenDesign also normalizes this shape before daemon-launched Codex runs, but manual cleanup may still be needed when Codex itself is invoked directly before OpenDesign gets a chance to patch the config.