Run Codex GUI from Source
This page walks you through starting Vite and Codex from source in a fresh clone, then opening the development page with /gui.
1. Prepare your development environment
Install the following tools first:
| Tool | Required version |
|---|---|
| Git | Current stable release |
| Node.js | ^22.18.0 or >=24.12.0 |
| pnpm | 10.33.0 |
| Rust | 1.95.0, pinned by the repository's rust-toolchain.toml |
| just | Current stable release |
| Python | Python 3 |
macOS, Linux, and Windows 11 with WSL2 are supported. Windows users should run the Linux commands below inside a WSL2 distribution; this workflow does not support native PowerShell.
2. Clone the repository
git clone https://github.com/jiangshengdev/codex.git
cd codex
git switch test
3. Install project dependencies
First, install the frontend dependencies for Codex GUI:
cd codex-gui
pnpm install --frozen-lockfile
cd ..
Then prepare the Rust dependencies through the repository's setup command:
just install
4. Start Vite
Open your first terminal and run the following from the repository root:
cd codex-gui
export CODEX_GUI_VITE_HOST=0.0.0.0
export CODEX_GUI_VITE_PORT=5173
pnpm run dev
Vite is running when you see the following address:
Local: http://localhost:5173/
5. Run Codex from source
Keep Vite running, then open a second terminal and go to the repository root:
export CODEX_GUI_HOST_MODE=dev
export CODEX_GUI_VITE_URL=http://127.0.0.1:5173
export NO_PROXY=127.0.0.1,localhost
just c
These export commands apply only to the current terminal and its child processes. You can also add these variables to your shell configuration to suit your development workflow. Codex uses the local Vite development server when launched from an environment where CODEX_GUI_HOST_MODE=dev is set.
Environment variables
| Variable | Purpose |
|---|---|
CODEX_GUI_HOST_MODE | Set to dev to make GUI Host proxy the Vite development server. |
CODEX_GUI_VITE_URL | The address GUI Host uses to access Vite. Defaults to http://127.0.0.1:5173. |
CODEX_GUI_VITE_HOST | The address Vite listens on. Defaults to 0.0.0.0. |
CODEX_GUI_VITE_PORT | The port Vite listens on. Defaults to 5173; if you change it, you must also update CODEX_GUI_VITE_URL. |
NO_PROXY | Prevents the system proxy from intercepting requests to 127.0.0.1 and localhost. |
CODEX_GUI_VITE_HMR_HOST | Optional; overrides the HMR host for remote or local network development. |
CODEX_GUI_VITE_HMR_PORT | Optional; overrides the HMR port for remote or local network development. |
CODEX_GUI_PACKAGE_ROOT is only used in prod mode to locate the built dist directory. You do not need to set it when starting in development mode.
6. Open the development GUI
Enter the following directly in Codex:
/gui
You do not need to send a regular message first. Copy the complete Local URL from the output, including /task/... and #token=..., and paste it into your browser's address bar.
Your development environment is ready when the page displays the current task and Vite is still running in the first terminal.