mirror of
https://github.com/openai/codex.git
synced 2026-05-28 23:10:20 +00:00
36a71a88bf
## Why `codex sandbox` now always runs the host sandbox backend, so it should accept the same profile selection mechanism as the rest of the runtime CLI surface. Without `--profile`, sandbox debugging can exercise only the default config stack unless users manually translate profile config into ad hoc `-c` overrides. Supporting `--profile` lets sandbox invocations load `$CODEX_HOME/<name>.config.toml`, including permission profile configuration, before resolving the sandbox policy for the command being run. ## What Changed - Added `--profile NAME` / `-p NAME` to the host-specific `codex sandbox` argument structs as `config_profile`. - Allowed root-level `codex --profile NAME sandbox ...` and made a sandbox-local `codex sandbox --profile NAME ...` override the root selection. - Threaded `LoaderOverrides` through sandbox config loading so selected config profile files participate in permission resolution before the legacy read-only fallback. - Documented the new sandbox flag in `codex-rs/README.md`. ## Verification - Added parser coverage for `codex sandbox --profile`. - Added sandbox config-loader coverage that verifies selected config profile loader overrides select the profile config rather than falling back to read-only. - Ran `cargo test -p codex-cli`.
100 lines
5.2 KiB
Markdown
100 lines
5.2 KiB
Markdown
# Codex CLI (Rust Implementation)
|
|
|
|
We provide Codex CLI as a standalone executable to ensure a zero-dependency install.
|
|
|
|
## Installing Codex
|
|
|
|
Today, the easiest way to install Codex is via `npm`:
|
|
|
|
```shell
|
|
npm i -g @openai/codex
|
|
codex
|
|
```
|
|
|
|
You can also install via Homebrew (`brew install --cask codex`) or download a platform-specific release directly from our [GitHub Releases](https://github.com/openai/codex/releases).
|
|
|
|
## Documentation quickstart
|
|
|
|
- First run with Codex? Start with [`docs/getting-started.md`](../docs/getting-started.md) (links to the walkthrough for prompts, keyboard shortcuts, and session management).
|
|
- Want deeper control? See [`docs/config.md`](../docs/config.md) and [`docs/install.md`](../docs/install.md).
|
|
|
|
## What's new in the Rust CLI
|
|
|
|
The Rust implementation is now the maintained Codex CLI and serves as the default experience. It includes a number of features that the legacy TypeScript CLI never supported.
|
|
|
|
### Config
|
|
|
|
Codex supports a rich set of configuration options. Note that the Rust CLI uses `config.toml` instead of `config.json`. See [`docs/config.md`](../docs/config.md) for details.
|
|
|
|
### Model Context Protocol Support
|
|
|
|
#### MCP client
|
|
|
|
Codex CLI functions as an MCP client that allows the Codex CLI and IDE extension to connect to MCP servers on startup. See the [`configuration documentation`](../docs/config.md#connecting-to-mcp-servers) for details.
|
|
|
|
#### MCP server (experimental)
|
|
|
|
Codex can be launched as an MCP _server_ by running `codex mcp-server`. This allows _other_ MCP clients to use Codex as a tool for another agent.
|
|
|
|
Use the [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) to try it out:
|
|
|
|
```shell
|
|
npx @modelcontextprotocol/inspector codex mcp-server
|
|
```
|
|
|
|
Use `codex mcp` to add/list/get/remove MCP server launchers defined in `config.toml`, and `codex mcp-server` to run the MCP server directly.
|
|
|
|
### Notifications
|
|
|
|
You can enable notifications by configuring a script that is run whenever the agent finishes a turn. The [notify documentation](../docs/config.md#notify) includes a detailed example that explains how to get desktop notifications via [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS. When Codex detects that it is running under WSL 2 inside Windows Terminal (`WT_SESSION` is set), the TUI automatically falls back to native Windows toast notifications so approval prompts and completed turns surface even though Windows Terminal does not implement OSC 9.
|
|
|
|
### `codex exec` to run Codex programmatically/non-interactively
|
|
|
|
To run Codex non-interactively, run `codex exec PROMPT` (you can also pass the prompt via `stdin`) and Codex will work on your task until it decides that it is done and exits. If you provide both a prompt argument and piped stdin, Codex appends stdin as a `<stdin>` block after the prompt so patterns like `echo "my output" | codex exec "Summarize this concisely"` work naturally. Output is printed to the terminal directly. You can set the `RUST_LOG` environment variable to see more about what's going on.
|
|
Use `codex exec --ephemeral ...` to run without persisting session rollout files to disk.
|
|
|
|
### Experimenting with the Codex Sandbox
|
|
|
|
To test to see what happens when a command is run under the sandbox provided by Codex, use the `sandbox` subcommand in Codex CLI:
|
|
|
|
```
|
|
# Uses the sandbox implementation for the current host OS:
|
|
# Seatbelt on macOS, the Linux sandbox on Linux, and Windows restricted token on Windows.
|
|
codex sandbox [COMMAND]...
|
|
|
|
# macOS-only diagnostic option
|
|
codex sandbox --log-denials [COMMAND]...
|
|
```
|
|
|
|
`codex sandbox` also accepts `--profile NAME` (`-p NAME`) to layer
|
|
`$CODEX_HOME/NAME.config.toml` onto the base user config for the sandboxed
|
|
command.
|
|
|
|
### Selecting a sandbox policy via `--sandbox`
|
|
|
|
The Rust CLI exposes a dedicated `--sandbox` (`-s`) flag that lets you pick the sandbox policy **without** having to reach for the generic `-c/--config` option:
|
|
|
|
```shell
|
|
# Run Codex with the default, read-only sandbox
|
|
codex --sandbox read-only
|
|
|
|
# Allow the agent to write within the current workspace while still blocking network access
|
|
codex --sandbox workspace-write
|
|
|
|
# Danger! Disable sandboxing entirely (only do this if you are already running in a container or other isolated env)
|
|
codex --sandbox danger-full-access
|
|
```
|
|
|
|
In `workspace-write`, Codex also includes `~/.codex/memories` in its writable roots so memory maintenance does not require an extra approval.
|
|
|
|
## Code Organization
|
|
|
|
This folder is the root of a Cargo workspace. It contains quite a bit of experimental code, but here are the key crates:
|
|
|
|
- [`core/`](./core) contains the business logic for Codex. Ultimately, we hope this becomes a library crate that is generally useful for building other Rust/native applications that use Codex.
|
|
- [`exec/`](./exec) "headless" CLI for use in automation.
|
|
- [`tui/`](./tui) CLI that launches a fullscreen TUI built with [Ratatui](https://ratatui.rs/).
|
|
- [`cli/`](./cli) CLI multitool that provides the aforementioned CLIs via subcommands.
|
|
|
|
If you want to contribute or inspect behavior in detail, start by reading the module-level `README.md` files under each crate and run the project workspace from the top-level `codex-rs` directory so shared config, features, and build scripts stay aligned.
|