# Codex CLI Setup: Install, Approval Modes and Sandboxing

> Set up OpenAI Codex CLI: install it, sign in, write a config.toml and profile files, and choose the sandbox mode and approval policy for each kind of task.

7 October 2026 · Technical · How-to · 8 min read · https://bridge-terminal.com/atlas/blog/codex-cli-install-approval-modes-sandbox/

## The short version

- Codex CLI is OpenAI's open-source (Apache-2.0) coding agent for the terminal. Install it with the install script, npm or Homebrew, run codex in a project folder, and sign in with ChatGPT or an API key.
- Two settings control what Codex can do: the sandbox mode (read-only, workspace-write or danger-full-access) limits what its commands can touch, and the approval policy (on-request or never) decides when it stops to ask you.
- The current CLI no longer has --full-auto or the untrusted approval policy. Use --sandbox workspace-write with -a on-request, or --approve-for-me, which sends approval requests to automatic review.
- Since Codex 0.134.0, profiles are separate files such as ~/.codex/review.config.toml, selected with --profile. [profiles.name] tables in config.toml are no longer read.
- Use --dangerously-bypass-approvals-and-sandbox (alias --yolo) only in an environment that is already isolated, and commit before each session so you can review and revert changes.

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:

```bash
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:

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

On Windows, there is a PowerShell installer:

```powershell
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:

```bash
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:

```bash
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`):

| Mode | What it allows |
|---|---|
| `read-only` | Codex can inspect files but can't edit them or run commands without approval |
| `workspace-write` | Read files, edit inside the workspace, run routine local commands there; network off by default |
| `danger-full-access` | No sandbox restrictions |

```bash
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.

```bash
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`:

```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`:

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

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://bridge-terminal.com/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.

## Questions people ask

### How do I install OpenAI Codex CLI?

On macOS or Linux, run `curl -fsSL https://chatgpt.com/codex/install.sh | sh`. You can also use `npm install -g @openai/codex` or, on macOS, `brew install --cask codex`. Windows has a PowerShell installer, and the openai/codex GitHub releases page has binaries for macOS and Linux. Then run `codex` in your project folder.

### How do I sign in to Codex CLI?

On first run, choose Sign in with ChatGPT, which uses your ChatGPT plan, or use an API key, which is billed to your OpenAI Platform account at API rates. `codex login` signs you in with ChatGPT outside a session, and `codex login --with-api-key` reads a key from standard input. OpenAI recommends API keys for CI.

### What is the difference between sandbox mode and approval policy in Codex?

Sandbox mode is enforced by the operating system (Seatbelt on macOS, bubblewrap and seccomp on Linux, the native sandbox on Windows). It limits which files commands can write and whether they can reach the network. Approval policy (on-request or never) decides when Codex stops to ask you.

### What happened to --full-auto and the untrusted approval policy?

Both are gone. `--full-auto` is no longer supported. Use `--sandbox workspace-write --ask-for-approval on-request`, or `--approve-for-me` to send approvals to automatic review. `untrusted` has been retired; OpenAI suggests `read-only` with `on-request` for cautious interactive use. `on-failure` is deprecated.

### What is a safe default config.toml for Codex CLI?

Put `approval_policy = "on-request"` and `sandbox_mode = "workspace-write"` in ~/.codex/config.toml, with `network_access = false` under `[sandbox_workspace_write]`. For a read-only setup, create ~/.codex/review.config.toml and run `codex --profile review`. Use `-c` to turn on network access for a single run.

## About Atlas: From per-command approvals to project-level guardrails

Codex's approval policy decides when one agent asks before acting. Atlas, a team of AI engineers built on Claude Code, also sets rules for the whole project: production go-lives, spending, deleting data, sending anything outside and dropping scope are never decided for you. Secrets pasted into chat go to a secret store first, and an optional daily budget warns at 50% and 80% and pauses the team at 100%. — https://bridge-terminal.com/atlas/

## Sources

- [Codex CLI – OpenAI docs](https://learn.chatgpt.com/docs/codex/cli)
- [Agent approvals & security – OpenAI Codex docs](https://learn.chatgpt.com/docs/agent-approvals-security)
- [Sandboxing – OpenAI Codex docs](https://learn.chatgpt.com/docs/sandboxing)
- [Codex CLI command reference – OpenAI docs](https://learn.chatgpt.com/docs/developer-commands?surface=cli)
- [Advanced configuration (profiles) – OpenAI Codex docs](https://learn.chatgpt.com/docs/config-file/config-advanced)
- [Non-interactive mode – OpenAI Codex docs](https://learn.chatgpt.com/docs/non-interactive-mode)
- [Authentication – OpenAI Codex docs](https://learn.chatgpt.com/docs/auth)
- [openai/codex on GitHub](https://github.com/openai/codex)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._