Codex CLI Setup: Install, Approval Modes and Sandboxing

To set up OpenAI Codex CLI, install it, run codex in a project folder, and sign in with your ChatGPT account or an API key. Then decide how much Codex may do without asking you. Two settings control that. The sandbox mode limits what its commands can touch. The approval policy decides when it has to stop and ask. This guide covers both, plus a config.toml and profile files you can reuse.

Codex has changed a lot in recent releases. --full-auto and the untrusted approval policy are gone, and profiles have moved into separate files. Many older guides still show the earlier syntax, so this one points out where things changed.

What Codex CLI is

Codex CLI is OpenAI's coding agent for the terminal. It is open source under the Apache-2.0 licence, in the openai/codex repository on GitHub. It reads your repository, edits files and runs commands such as tests and builds. Because it acts on your machine, the sandbox and approval settings matter more than which model you pick.

Installing Codex CLI

On macOS and Linux, the standalone installer is:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Running the same command again updates Codex. You can also install it with a package manager:

npm install -g @openai/codex
# or, on macOS
brew install --cask codex

On Windows, there is a PowerShell installer:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The GitHub releases page also has prebuilt binaries for macOS (Apple silicon and Intel) and Linux (x86_64 and arm64). Each archive contains one file with the platform in its name, so you will usually rename it to codex after extracting it.

Signing in

Start Codex from the root of a project:

cd my-project
codex

On first run, Codex asks how you want to authenticate:

• Sign in with ChatGPT. Usage comes out of your ChatGPT plan, and you don't need to manage API keys.
• Use an API key. OpenAI bills this usage to your OpenAI Platform account at standard API rates. OpenAI recommends API keys for automation such as CI jobs.

You can also sign in without starting a session. codex login opens a browser for the ChatGPT sign-in, and --with-api-key reads a key from standard input:

codex login
printenv OPENAI_API_KEY | codex login --with-api-key

Approval policy vs sandbox mode

Setup often goes wrong because people treat these as one setting. There are two:

• Sandbox mode is enforced by the operating system. It limits which files Codex's commands can write and whether they can reach the network. If the sandbox blocks something, it stays blocked, whatever the model decides.
• Approval policy decides when Codex stops for your OK, for example before it goes outside the sandbox.

A tight sandbox with few prompts is often safer than a loose sandbox with many prompts. If you're asked to approve something every few seconds, you will soon start approving without reading.

Sandbox modes

Set the sandbox mode with --sandbox (or -s):

codex --sandbox read-only
codex --sandbox workspace-write

workspace-write is the default for local work. Codex can edit your project and run your test suite, but it can't write outside the workspace, and it has no network access unless you turn it on.

How the sandbox is enforced

Codex uses operating-system features to enforce the sandbox, so it doesn't depend on the model following instructions:

• macOS: Apple's built-in Seatbelt framework. It works without any setup.
• Linux and WSL2: bubblewrap (bwrap) together with seccomp. The docs say to install bubblewrap with your package manager first. Otherwise Codex falls back to a bundled helper, which needs unprivileged user namespaces.
• Windows: the native Windows sandbox when you run Codex in PowerShell. Under WSL2, Codex uses the Linux sandbox. WSL1 support ended with version 0.115.

The limits apply to the commands Codex runs, including test scripts and install commands. If your environment can't provide these features, run Codex inside a container or VM that is already isolated, and loosen Codex's own sandbox only there.

Approval policies

Set the approval policy with --ask-for-approval (or -a). The CLI accepts two values:

• on-request: Codex edits and runs commands inside the sandbox, and asks before it goes outside it, for example to use the network.
• never: Codex never asks. If the sandbox blocks something, the action fails.

codex --sandbox workspace-write --ask-for-approval on-request

In config.toml there is also a granular form. It keeps some kinds of approval prompt interactive and rejects the rest automatically.

Two older values no longer work. untrusted has been retired, and OpenAI says to remove it from your config. For cautious interactive use, it suggests read-only with on-request. on-failure is deprecated. The config reference says to use on-request for interactive runs and never for runs nobody is watching.

Shortcut flags

• --sandbox workspace-write --ask-for-approval on-request is the "Auto" preset. Codex works inside the project and asks only when it needs to go further. This suits most day-to-day coding in a repository under version control.
• --approve-for-me (alias --not-so-yolo) uses the workspace-write sandbox with on-request approvals, but sends approval requests to an automatic review step instead of to you.
• --dangerously-bypass-approvals-and-sandbox (alias --yolo) runs every command without approvals and without a sandbox. The docs say to use it only inside an environment that is already hardened, such as a throwaway container or VM.

--full-auto is no longer supported. If an old script uses it, replace it with --sandbox workspace-write or --approve-for-me.

In a session, /permissions lets you change when Codex can edit files or run commands without asking, and shows the current sandbox and the folders it can write to. /status shows the session's current configuration.

A practical config.toml

Flags are fine for one-off runs. For settings you want every time, use ~/.codex/config.toml:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

Network access is already off by default. Setting it explicitly makes the choice visible to anyone reading the file.

This example doesn't set model, so Codex uses its default. To pin a model, add model = "..." with a model your account or workspace can use.

Codex also has newer permission profiles. You define them under [permissions.<name>] and select one with default_permissions. They can set rules per path, such as denying .env files, and limit network access to a list of allowed domains. They don't combine with sandbox_mode or [sandbox_workspace_write], so choose one approach per config.

Profiles for different levels of trust

Profiles let you keep several setups and choose one for each run. Since Codex 0.134.0, each profile is its own file in ~/.codex, named <profile>.config.toml. It uses top-level keys and contains only the values that differ from your base config. --profile no longer reads [profiles.<name>] tables in config.toml, so move any you have into separate files.

~/.codex/review.config.toml:

approval_policy = "on-request"
sandbox_mode = "read-only"

codex --profile review

A read-only review profile works well when you're exploring an unfamiliar codebase or asking Codex to explain code. Run without the profile when you want it to make changes under the base config.

One-off overrides

You can override any config key for one run with -c:

codex -c sandbox_workspace_write.network_access=true

Use this when a task needs the network, such as installing a dependency, instead of turning network access on for every run.

Project instructions with AGENTS.md

Codex reads AGENTS.md files before it starts any work. It reads a global one from ~/.codex, then walks from the project root (usually the git root) down to your current directory, reading the AGENTS.md in each folder along the way. Running /init in a session creates one for you to edit.

Keep it short and concrete:

• The exact commands for install, lint, test and build
• Directories that are generated or vendored and shouldn't be edited
• Conventions a reviewer would otherwise flag

Running Codex without the interactive UI

For scripts and CI, codex exec (alias codex e) runs a task and exits:

codex exec "explain why the test suite is failing"

By default, codex exec runs in a read-only sandbox, so Codex can't edit files. To let it make changes, grant write access explicitly:

codex exec --sandbox workspace-write "update the changelog for the latest commits"

In CI, set the API key only on the command that needs it, not for the whole job:

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

The docs warn against setting OPENAI_API_KEY or CODEX_API_KEY at job level when the job runs code from the repository, because build scripts or tests in that job could read the key. Keep the sandbox as narrow as the job allows. Nobody is reading prompts in a pipeline.

Choosing settings: a simple ladder

If you're not sure where to start, work up this list:

1. Exploring: read-only with on-request. Codex can read and explain code, but it can't change anything unless you approve it.
2. Everyday coding: workspace-write with on-request, network off. Commit before each session so git diff shows exactly what changed.
3. Tasks that need the network: the same setup, plus -c sandbox_workspace_write.network_access=true for that run only.
4. Fully unattended: --yolo only inside a disposable container or VM, never against your laptop's home directory.

Two habits matter more than the exact setting. Work on a clean git branch so you can review and revert any change. And read each command before you approve it, because approval prompts only protect you if someone reads them.

Beyond a single agent

Approval policies govern one agent, one action at a time. When several agents work on the same product, you also need rules at the project level, such as who approves a production release and who can spend money or delete data. Atlas, a team of AI engineers built on Claude Code, never makes those decisions itself: production go-lives, spending, deleting data, sending anything outside and dropping scope always go to a person.

Summary

Installing Codex CLI takes a few minutes: install it, run codex, sign in. Most of the setup is choosing the sandbox (what Codex can touch) and the approval policy (when it asks), then saving both in ~/.codex/config.toml. For most projects, start with workspace-write, on-request and network off. Add a read-only profile file for exploring, and use the full bypass only in a disposable environment. Flags have been renamed and removed recently, so check codex --help for your installed version before you put a flag in a script.