Skip to main content
This guide covers the prerequisites and steps needed to set up a development environment for Codex CLI.

​
System Requirements

Ensure your system meets these minimum requirements before proceeding.
RequirementDetails
Operating systemsmacOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2
RAM4 GB minimum (8 GB recommended)
Git2.23+ (optional, recommended for built-in PR helpers)

​
Rust Development Setup

The primary Codex CLI implementation is written in Rust and lives in the codex-rs/ directory.
1

Clone the Repository

git clone https://github.com/openai/codex.git
cd codex/codex-rs
2

Install Rust Toolchain

Install Rust and required components:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup component add rustfmt
rustup component add clippy
3

Install Helper Tools

Install workspace helper tools:
# Required: justfile command runner
cargo install just

# Optional: nextest for faster test runs
cargo install --locked cargo-nextest

# Optional: insta for snapshot testing
cargo install cargo-insta
4

Verify Installation

Build Codex to verify your setup:
cargo build
If the build succeeds, you’re ready to start developing!

​
TypeScript Development Setup

The TypeScript implementation is legacy and has been superseded by the Rust implementation. This section is provided for reference only.
The legacy TypeScript CLI lives in the codex-cli/ directory.
1

Navigate to CLI Directory

cd codex/codex-cli
2

Enable Corepack

corepack enable
3

Install Dependencies

pnpm install
4

Linux-Only: Download Sandboxing Binaries

On Linux, download prebuilt sandboxing binaries (requires gh and zstd):
./scripts/install_native_deps.sh

​
DotSlash (Optional)

GitHub Releases contain a DotSlash file for the Codex CLI named codex. Using a DotSlash file makes it possible to commit a lightweight reference to source control to ensure all contributors use the same version of an executable, regardless of platform.

​
Alternative: Nix Flake Development

Prerequisite: Nix >= 2.4 with flakes enabled (experimental-features = nix-command flakes in ~/.config/nix/nix.conf).

​
Enter Development Shell

# For Rust implementation
nix develop .#codex-rs

# For TypeScript implementation
nix develop .#codex-cli
This shell includes Node.js (for TypeScript) or Rust toolchain, installs dependencies, builds the CLI, and provides a codex command alias.

​
Build Directly

# Build Rust implementation
nix build .#codex-rs
./result/bin/codex --help

# Build TypeScript implementation
nix build .#codex-cli
./result/bin/codex --help

​
Run via Flake App

# Run Rust implementation
nix run .#codex-rs

# Run TypeScript implementation
nix run .#codex-cli

​
Use with direnv

If you have direnv installed, automatically enter the Nix shell when you cd into the project:
cd codex-rs
echo "use flake ../flake.nix#codex-rs" >> .envrc && direnv allow

cd ../codex-cli
echo "use flake ../flake.nix#codex-cli" >> .envrc && direnv allow

​
Next Steps

Now that your environment is set up:

Building

Learn how to build the project

Testing

Run tests to verify your setup

Guidelines

Review contribution guidelines

Configuration

Explore configuration options