mirror of
https://github.com/openai/codex.git
synced 2026-04-24 14:45:27 +00:00
c1ff22bc6c
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.
2.9 KiB
2.9 KiB
Installing & building
System requirements
| Requirement | Details |
|---|---|
| Operating systems | macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2 |
| Git (optional, recommended) | 2.23+ for built-in PR helpers |
| RAM | 4-GB minimum (8-GB recommended) |
Install via curl
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/installer/install.sh | bash
The curl installer writes under CODEX_HOME (default: ~/.codex). See
installer/README.md for the detailed layout and mechanics.
DotSlash
The GitHub Release also contains a DotSlash file for the Codex CLI named codex. Using a DotSlash file makes it possible to make a lightweight commit to source control to ensure all contributors use the same version of an executable, regardless of what platform they use for development.
Build from source
# Clone the repository and navigate to the root of the Cargo workspace.
git clone https://github.com/openai/codex.git
cd codex/codex-rs
# Install the Rust toolchain, if necessary.
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
# Install helper tools used by the workspace justfile:
cargo install just
# Optional: install nextest for the `just test` helper
cargo install cargo-nextest
# Build Codex.
cargo build
# Launch the TUI with a sample prompt.
cargo run --bin codex -- "explain this codebase to me"
# After making changes, use the root justfile helpers (they default to codex-rs):
just fmt
just fix -p <crate-you-touched>
# Run the relevant tests (project-specific is fastest), for example:
cargo test -p codex-tui
# If you have cargo-nextest installed, `just test` runs the test suite via nextest:
just test
# If you specifically want the full `--all-features` matrix, use:
cargo test --all-features
Tracing / verbose logging
Codex is written in Rust, so it honors the RUST_LOG environment variable to configure its logging behavior.
The TUI defaults to RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info and log messages are written to ~/.codex/log/codex-tui.log, so you can leave the following running in a separate terminal to monitor log messages as they are written:
tail -F ~/.codex/log/codex-tui.log
By comparison, the non-interactive mode (codex exec) defaults to RUST_LOG=error, but messages are printed inline, so there is no need to monitor a separate file.
See the Rust documentation on RUST_LOG for more information on the configuration options.