openai/codex
1
0
Fork 0
mirror of https://github.com/openai/codex.git synced 2026-09-15 12:08:01 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
pr9864
codex/README.md
Michael Bolin c1ff22bc6c feat: This PR adds a first-party curl-based installer that downloads only the binaries needed for the current platform and wires it into Codex’s existing update UX. 
It introduces a dedicated `installer/` folder for non-Rust install/update assets, a `CODEX_HOME`-aware on-disk layout, and a wrapper that makes helper CLIs available to Codex without globally polluting the user’s shell.

## Why

Today the recommended install path is `npm i -g @openai/codex`, but the npm package bundles native binaries for all platforms (and `rg`), leading to very large installs (hundreds of MB unpacked) even though a single platform binary is much smaller.

Homebrew avoids this on macOS by downloading only the matching artifact. This PR brings that same property to a cross-platform one-liner:

```sh
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/installer/install.sh | bash
```

Key goals:

- Download only the user’s platform artifacts.
- Keep curl-managed installs isolated under `CODEX_HOME`.
- Preserve compatibility with npm/brew installs (shadowing is fine, breaking is not).
- Provide a clean place to add helper CLIs that should be available when Codex runs.

## How It Works

### Install root and layout

All curl-managed artifacts live under `CODEX_HOME` (default: `~/.codex`).

The layout is:

- `CODEX_HOME/bin/`
- `CODEX_HOME/versions/<version>/bin/`
- `CODEX_HOME/versions/current` (symlink)
- `CODEX_HOME/tools/bin/`

This design supports atomic version switches and helper CLIs:

- The user’s global `PATH` only needs `CODEX_HOME/bin`.
- The runtime `PATH` is extended inside the wrapper to include helper CLIs.

See `installer/README.md:1`.

### Installer scripts

#### `installer/install.sh`

`installer/install.sh:1` is the public entrypoint:

- Requires Bash explicitly (we use Bash features like `mapfile`).
- Loads `installer/lib.sh` locally when run from a checkout, or downloads it when piped from curl.
- Detects `arch`/`os`, resolves the version (via `CODEX_VERSION` or GitHub Releases), downloads the correct tarball, installs it, activates it, and updates the user’s rc file.

#### `installer/lib.sh`

`installer/lib.sh:10` centralizes the mechanics:

- Resolves `CODEX_HOME` with a fallback to `~/.codex`.
- Detects OS/arch and builds release URLs.
- Idempotently updates the user rc file via a marker block that respects non-default `CODEX_HOME` values: `installer/lib.sh:106`.
- Installs a wrapper at `CODEX_HOME/bin/codex` that:
  - Sets `CODEX_MANAGED_BY_CURL=1`.
  - Extends `PATH` at runtime to include:
    - `CODEX_HOME/bin`
    - `CODEX_HOME/tools/bin`
    - `CODEX_HOME/versions/current/bin`
  - Execs the active versioned binary: `installer/lib.sh:154`.
- Installs the tarball into a versioned `bin/` directory and preserves any additional CLIs present in the tarball (not just `codex`): `installer/lib.sh:181`.
- Keeps the last two installed versions and avoids deleting the `current` symlink: `installer/lib.sh:239`.

#### `installer/update.sh`

`installer/update.sh:1` mirrors the installer flow but always targets the latest release.

### Update UX integration in the CLI

Codex’s update prompt already knows how to run a package-manager-specific update command after the TUI exits.

This PR adds a curl-managed update action in `codex-rs/tui/src/update_action.rs:3`:

- Adds `UpdateAction::CurlInstallerUpdate`.
- Detects curl-managed installs via `CODEX_MANAGED_BY_CURL` (set by the wrapper): `codex-rs/tui/src/update_action.rs:40`.
- Uses the curl updater one-liner for the update command: `codex-rs/tui/src/update_action.rs:21`.

This keeps update behavior consistent with npm/brew while avoiding fragile path heuristics.

## Docs updates

- The curl installer is now the first recommended install path in `README.md:1` and `README.md:18`.
- `docs/install.md:11` adds a curl install section and points to `installer/README.md` for the detailed mechanics.

## Compatibility and safety notes

- This does not modify npm or Homebrew installs.
- The rc-file change only adds `CODEX_HOME/bin` to `PATH`.
- Additional helper CLIs are available to Codex via the wrapper’s runtime `PATH`, rather than being forced into the user’s global shell.
- The installer honors `CODEX_HOME` everywhere, falling back to `~/.codex`.

## Testing

Commands run:

```sh
cd codex-rs
just fmt
cargo test -p codex-tui
```

Notes:

- In this environment, `cargo test -p codex-tui` required running outside the sandbox due to a macOS `SystemConfiguration` panic; it passed once run with escalated permissions.
- No new VS Code diagnostics were reported.

## Follow-ups (explicitly not in this PR)

- Ensure the release tarballs include any helper CLIs we expect to be available at runtime (for example, Windows sandbox helpers).
- Add an explicit `codex self-update` command that delegates to `installer/update.sh`.
- Decide how we want to manage third-party tools like `rg` under `CODEX_HOME/tools/` and whether the CLI should probe a managed fallback path.
2026-01-25 21:09:29 -08:00

67 lines
2.7 KiB
Markdown
Raw Permalink Blame History

<p align="center"><code>curl -fsSL https://raw.githubusercontent.com/openai/codex/main/installer/install.sh | bash</code><br />or <code>brew install --cask codex</code><br />or <code>npm i -g @openai/codex</code></p>
<p align="center"><strong>Codex CLI</strong> is a coding agent from OpenAI that runs locally on your computer.
<p align="center">
<img src="./.github/codex-cli-splash.png" alt="Codex CLI splash" width="80%" />
</p>
</br>
If you want Codex in your code editor (VS Code, Cursor, Windsurf), <a href="https://developers.openai.com/codex/ide">install in your IDE.</a>
</br>If you are looking for the <em>cloud-based agent</em> from OpenAI, <strong>Codex Web</strong>, go to <a href="https://chatgpt.com/codex">chatgpt.com/codex</a>.</p>
---
## Quickstart
### Installing and running Codex CLI
Install globally with your preferred package manager:
```shell
# Install using curl
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/installer/install.sh | bash
```
If you want to install somewhere other than `~/.codex`, set `CODEX_HOME` first.
```shell
# Install using npm
npm install -g @openai/codex
```
```shell
# Install using Homebrew
brew install --cask codex
```
Then simply run `codex` to get started.
<details>
<summary>You can also go to the <a href="https://github.com/openai/codex/releases/latest">latest GitHub Release</a> and download the appropriate binary for your platform.</summary>
Each GitHub Release contains many executables, but in practice, you likely want one of these:
- macOS
- Apple Silicon/arm64: `codex-aarch64-apple-darwin.tar.gz`
- x86_64 (older Mac hardware): `codex-x86_64-apple-darwin.tar.gz`
- Linux
- x86_64: `codex-x86_64-unknown-linux-musl.tar.gz`
- arm64: `codex-aarch64-unknown-linux-musl.tar.gz`
Each archive contains a single entry with the platform baked into the name (e.g., `codex-x86_64-unknown-linux-musl`), so you likely want to rename it to `codex` after extracting it.
</details>
### Using Codex with your ChatGPT plan
Run `codex` and select **Sign in with ChatGPT**. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. [Learn more about what's included in your ChatGPT plan](https://help.openai.com/en/articles/11369540-codex-in-chatgpt).
You can also use Codex with an API key, but this requires [additional setup](https://developers.openai.com/codex/auth#sign-in-with-an-api-key).
## Docs
- [**Codex Documentation**](https://developers.openai.com/codex)
- [**Contributing**](./docs/contributing.md)
- [**Installing & building**](./docs/install.md)
- [**Open source fund**](./docs/open-source-fund.md)
This repository is licensed under the [Apache-2.0 License](LICENSE).
Reference in New Issue View Git Blame Copy Permalink