Installation

Installation

You can install Codex Free from a prebuilt binary (fastest) or build it from source.

Prerequisites

• An OpenAI/ChatGPT account with Developer mode for the connector (a ChatGPT Plus/Pro subscription is what makes the connector usable).
• Git on your PATH if you want the git tools and review checkpoints to work (recommended).
• For the native OpenAI tunnel (recommended connection mode), you'll create a tunnel ID and a restricted runtime API key later — see Connecting to ChatGPT.
• To build from source only: a recent Rust toolchain (edition 2024).

Option A — Prebuilt binary (recommended)

Each release ships one native binary per platform:

Platform	Archive
Windows x64	windows-x64
Linux x64	linux-x64
Linux arm64	linux-arm64
macOS Intel	darwin-x64
macOS Apple Silicon	darwin-arm64

1. Download the archive for your OS/arch from the Releases page.
2. Verify the checksum against the published SHA256SUMS (each release publishes checksums alongside the archives).
3. Unpack it.
4. Put codex-free (or codex-free.exe) somewhere on your PATH.

These are native builds, so there is no AVX2/baseline caveat — the binary runs on any CPU of its architecture.

Verify it runs:

codex-free --help

Option B — Build from source

git clone https://github.com/hypnguyen1209/codex-free.git
cd codex-free
cargo build --release
# binary is at target/release/codex-free

You can also run without installing:

cargo run --release -- --work-dir /path/to/your/project

Everywhere this wiki writes codex-free …, the source-checkout equivalent is cargo run --release -- ….

Where Codex Free keeps its data

Codex Free never writes into the project you point it at. Its own state lives under your home directory in ~/.codex-free/:

Path	Holds
~/.codex-free/openai-tunnel/	The managed OpenAI tunnel client runtime and its pinned install manifest
~/.codex-free/openai-tunnel/credentials/	Per-tunnel runtime key files written by quickstart (Unix: mode 0700/0600)
~/.codex-free/projects/<name>-<hash>/memory.json	Per-project plan and notes (see Context and Memory)
~/.codex-free/conversation-projects/	Per-conversation project bindings in multi-project mode

It also reads (never rewrites) Codex's own config at $CODEX_HOME/config.toml (default ~/.codex/config.toml) to discover MCP servers and, in multi-project mode, project candidates.

Next step

Head to Quick Start for the guided setup, or CLI Reference if you'd rather wire everything by hand.