Windows and WSL

Use Vex from Windows with WSL

Run the Vex CLI and keep Vex repositories in your WSL Linux distribution. Windows desktop agents and WSL CLI profiles are separate environments.

Environment ownership

WSL Linux: Vex CLI, checkout, JJ data, and repository credentials.
WSL Codex CLI: Linux-side skill and MCP configuration for CLI sessions.
Windows desktop: ChatGPT/Codex desktop sign-in and Windows desktop settings.

vex setup writes only the current environment's profile. It does not copy skills, MCP configuration, or credentials between WSL and Windows.

Step 1

Use a Linux terminal

Install WSL2 and open your Linux distribution. Vex CLI, JJ data, repository credentials, and Linux-side agent configuration stay in that distribution.

mkdir -p ~/src && cd ~/src

Step 2

Install and verify Vex

Install into the Linux home. If the installer updates PATH, update the Linux shell file it names, restart the terminal, then verify the command.

curl -fsSL https://cli.cdn.vex.sc/install.sh | sh
vex --help

Step 3

Sign in and clone

Keep the checkout under the WSL filesystem, such as ~/src, rather than /mnt/c for normal Vex/JJ work.

vex login
vex whoami
vex clone <org>/home

Step 4

Set up your WSL agent

Run setup only in the environment that owns that agent profile. The Codex CLI bootstrap is stored in the WSL profile, not a Windows profile.

vex setup --yes --targets codex
vex setup doctor --format json

FUSE is optional in WSL

Start with a normal checkout. If you need a daemon-backed virtual working copy, check the Linux capability from inside WSL before mounting. Do not run mounts from a Windows path.

vex daemon capabilities --format json
mkdir -p ~/vex-mounts/home
vex mount ~/vex-mounts/home --repo ~/src/home --rev @ --read-write

If the capability report says FUSE is unavailable, keep using the ordinary WSL checkout; the non-FUSE virtual working-copy fallback remains available outside mounted paths.

Skills and live tools are separate

The installed Vex skill is an offline-safe bootstrap. When network access is permitted, it directs the model to https://vex.sc/skill.md for current guidance. MCP is a separate, explicit tool configuration:

vex setup --dry-run --targets codex --with-mcp

A Windows ChatGPT/Codex desktop session uses its own current folder and terminal workflow. Do not assume it reads the WSL ~/.codex profile or copy that profile into Windows. If the desktop app cannot use the WSL checkout or terminal, continue with the WSL Codex CLI path.

CLI configuration Source control docs