Codex CLI: installation, permissions, AGENTS.md, and costs

Codex CLI is OpenAI’s coding agent for the terminal: it can inspect a project, edit files, and run checks within the permissions you grant. Using it effectively means understanding the difference between installing the client, accessing the model, setting technical sandbox boundaries, and configuring approval rules. This guide covers those settings, AGENTS.md, and costs, using official sources consulted on October 24, 2026.

What you install and what you delegate

A Codex CLI session can help you understand a function, prepare a fix, or investigate a regression. Working in the terminal puts the agent alongside your project and its usual tools. You still need to recognize whether a command makes sense, review a file diff, and interpret test results.

The installed software and the service providing the model are separate components. The client’s license therefore determines neither your usage charges nor the terms governing how your data is processed. The official repository publishes the client under the Apache-2.0 license and documents its installation methods.

When deciding what to delegate, start with an observable outcome: fix a described behavior, explain a dependency, or add a specific check. A broad request to improve a project leaves more room for unnecessary changes and makes the result harder to review.

This guide is intended for people who can take over when a command fails. For a broader explanation of the approach, the article on how coding agents work describes their working loop. You can then explore individual profiles in our AI agent directory.

Prerequisites: prepare the project before starting

Have a working terminal, access to your chosen model service, and a working copy whose current state you understand. If you choose a package manager installation, that package manager must already be available. The commands below are alternatives: choose a single installation method.

Before starting:

Identify the exact folder you want the agent to inspect.
Back up existing changes and identify untracked files.
Check how the project is built and tested.
Remove unnecessary secrets from the working environment.
Define which operations require your approval.

A clean starting point makes it easier to identify who changed what. If several people or tools are editing the same files, use a separate workspace. This avoids having to ask the agent afterward to distinguish its changes from a colleague’s work.

Also prepare an example of the expected result. For a display issue, describe the visible behavior. For a data processing task, provide an anonymized example. A concrete success criterion is more useful than a long explanation of your intentions.

Remember that a test can itself write files, contact a service, or use credentials available in the environment. Review the project’s scripts before handing them over to an agent, especially when the repository comes from an unfamiliar source.

1. Install Codex CLI using an official method

The official getting started instructions offer a standalone installer for macOS and Linux. The following command, checked against the Codex CLI documentation, downloads and runs the installation script:

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

For Windows, the official repository provides this PowerShell command:

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

If you already use npm or Homebrew, the same repository documents these alternatives:

npm install -g @openai/codex

brew install --cask codex

Choose the method that fits your computer’s software installation policy. On a managed device, follow your organization’s approved distribution process. Avoid installing Codex through several methods at once: an older executable may retain priority in the terminal’s search path.

To update a standalone installation on macOS or Linux, the documentation says to run the same installer again. Before rolling out an update across a team, keep a record of the configuration in use and check its behavior on a project without sensitive data.

You do not need to pin a particular version to follow this guide. When documenting an incident, however, record the version actually installed. An option described in the current documentation may be missing from an older client.

2. Choose an authentication method and budget

Start the interactive sign-in process with:

codex login

The authentication documentation distinguishes signing in with a ChatGPT account from using an API key. The first uses the account’s or workspace’s entitlements; the second uses those of the API organization.

If your key is already available in the expected environment variable, the official command is:

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

This example assumes your shell provides printenv. Do not replace the variable with a plaintext key in a command you share. Use your environment’s secret management mechanism instead.

To check the active authentication method:

codex login status

For a machine without a browser, device code authentication is documented as a beta feature. It must be enabled in the account or workspace settings:

codex login --device-auth

Credentials may be stored in a local file or in the operating system’s credential store. Treat any authentication cache as a secret.

Before starting a costly task, check both the active account and the budget it will use. A successful login does not prove that usage will be charged against the budget your team intended.

3. Separate approvals from sandboxing

The sandbox sets technical boundaries: which files commands can access, where they can write, and whether they can use the network. The approval policy determines when an action must be submitted for approval. Instructions written in the conversation form another separate layer.

As of October 24, 2026, the sandboxing documentation describes the following legacy modes and states that the untrusted policy can no longer be selected.

Legacy setting	Inspection	Writing	Suggested use
`read-only`	Inspect the project	No editing within the normal scope	Initial diagnosis
`workspace-write`	Read accessible files	Write within the authorized workspace	A clearly scoped fix
`danger-full-access`	Access without sandbox restrictions	No sandbox boundary	An isolated, prepared environment

The current approval policies are on-request and never. The latter removes approval prompts. It should not be interpreted as editorial or business authorization for every possible action.

On Linux and WSL2, the documentation recommends installing bubblewrap. For Ubuntu or Debian:

sudo apt install bubblewrap

For Fedora:

sudo dnf install bubblewrap

Follow the procedure for your operating system. If isolation fails, investigate the technical cause before expanding permissions.

In practice, start with the principle of least privilege: grant access to the project involved, then expand the scope only when a specific step requires it. Faster execution alone does not justify access to personal folders or production credentials.

4. Start with explicit permissions

The options below appear in the official command reference, consulted on October 24, 2026. Run this command from the project folder to allow inspection without escalation requests:

codex --sandbox read-only --ask-for-approval never

To work on a fix within the authorized workspace, requesting approval when necessary:

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

The reference also provides an option for automatic review of eligible approval requests:

codex --approve-for-me

This option uses a sandbox that permits writing within the workspace. It conflicts with certain manual sandbox and approval options, so do not combine them.

Choose the mode to match the task. Code analysis generally does not require the same permissions as a dependency migration. Publishing, sending data, or changing infrastructure deserves a separate decision from granting permission to edit files.

Human approval requires reading both the command and its context. Before approving, identify the affected folder, any network destinations, and effects that will persist afterward. If the request does not make those details clear, ask for a more precise description of the action.

Avoid turning a one-time authorization into a general permission for convenience. The guide to securing an AI agent applies this approach beyond terminal use.

Permission profiles: a separate configuration system

The current documentation also offers permission profiles in beta. These include :read-only, :workspace, and :danger-full-access, using syntax that differs from the legacy modes.

A minimal configuration choice can look like this:

default_permissions = ":read-only"

These profiles do not combine with the legacy sandbox_mode and sandbox_workspace_write settings. An existing legacy setting or corresponding launch option can cause the legacy system to be used. An administrator-enforced list of profiles is a documented exception.

When preparing a migration, explicitly choose which system to use. Review every configuration layer that is loaded, then check reading, writing, and network access separately. In a managed environment, the available profiles may be restricted.

The practical implication is straightforward: copying a configuration example without reviewing existing settings can produce different behavior from what you expect. Keep the configuration short and explain the reason for each exception.

Also prepare checks using dummy data to confirm that prohibited actions fail. An attempt to write outside the permitted scope should fail when that boundary is required. Do not test this by requesting a dangerous operation on real files.

Keep a record of effective permissions alongside your team’s procedures. That record is more useful for troubleshooting than a copy of the personal preferences of whoever installed the tool.

5. Write a short, verifiable AGENTS.md

AGENTS.md communicates the project’s working conventions. According to the official AGENTS.md documentation, Codex combines global instructions with instructions discovered between the project root and the current directory.

Within each folder, AGENTS.override.md takes precedence over AGENTS.md. Instructions closer to the current directory come after the general instructions. After making changes, restart the session to rebuild the instruction chain.

Here is an illustrative template to adapt. It does not assume a particular test command:

# Project rules

## Scope
- Limit changes to the stated request.
- Flag any necessary changes outside the intended scope.
- Do not publish or deploy without explicit approval.

## Checks
- Read the project scripts before running checks.
- Run checks relevant to the modified files.
- Distinguish checks that passed, failed, or were not run.

## Handoff
- Explain the behavior that was fixed.
- Report limitations and decisions that remain open.

To inspect the instructions being applied, the documentation provides:

codex --ask-for-approval never "Summarize the current instructions."

Review the response against the files you expect to be included. This inspection can help uncover an override you had forgotten.

Avoid vague rules and requirements that cannot realistically be followed. Point to the relevant procedures rather than copying all the documentation into the file. Above all, a written prohibition is not a technical access restriction: also protect resources the agent should not be able to reach.

6. Complete a task, then review the result

Start with a request whose scope is clear. For example, ask the agent to investigate a validation failure, propose a limited fix, and identify the checks needed. This is an example task description, not a reported result.

Then proceed in this order:

Establish the diagnosis. Ask for the affected files, the proposed explanation, and the evidence supporting it.
Check the scope. Confirm that the proposed fix addresses the defect without unrelated rewrites.
Authorize the appropriate edits. Use the permissions required for the intended change.
Examine the checks. Look for a check that would have caught the original defect.
Review the complete diff. Include dependencies, configuration, and generated files.
Decide whether to integrate. Make this decision after reviewing the work.

A passing check provides evidence only for what it covers. A test suite may miss an accessibility issue, incorrectly migrated data, or exposed information. Match the evidence you require to the risk of the change.

Also request an accurate account of checks that were not run. A blocked dependency installation, an unavailable service, or an incomplete environment should remain visible in the handoff.

The detailed guide to working with a coding agent explains how to break requests into manageable tasks. The method still applies when the model or interface changes.

Costs: separate subscriptions, API usage, and human work

The official pricing page, consulted on October 24, 2026, lists Plus at approximately $20 per month and Pro starting at approximately $100 per month. Check your account’s eligibility and the features available in the CLI before choosing a plan.

Criterion	ChatGPT sign-in	API key
Allowance	Plan entitlements and limits	Usage billed through the API
Monitoring	Account usage dashboard	API organization usage tracking
What to watch	Shared credits and usage	Consumption from automated tasks

Limits depend on factors including the model, context size, and task complexity. A user message therefore does not have a fixed cost. The following session command shows remaining limits when that information is available:

/status

When budgeting, separate service charges, tool execution costs, and review time. Measure the cost of an accepted task, including revisions, rather than the cost of its first response.

Define the scope before starting, and stop investigations that no longer produce useful evidence. A concise request can still require substantial work, so monitor both the result and the usage needed to produce it.

The article on the real cost of an AI agent explores this further. For an estimate based on identified token volumes, use the LLM pricing calculator.

Common problems

The terminal cannot find Codex. Check the installation method and executable search path. Reopen the terminal after changing that environment. Reinstalling through a different method may make the problem harder to diagnose.

Sign-in works, but expected access is missing. Check the authentication method, active account, and active workspace. Then check administrative permissions and the associated plan. Do not immediately assume the installation is faulty.

The agent can read files but cannot edit them. Review the effective permissions and working directory. If the task is inspection only, this behavior may be correct. Otherwise, grant write access within the necessary scope.

The rules seem to be ignored. Look for an override file and check the directory from which you launched the session. Compare the summarized instructions with those you expected, then start a fresh session.

Tests fail after the fix. Distinguish a newly introduced defect from a preexisting problem or missing dependency. Keep useful error messages and avoid making successive changes without an explicit hypothesis.

The task keeps expanding without producing a reviewable result. Ask the agent to pause and report the files changed, findings established, and remaining uncertainties. Resume with a narrower request.

In each case, change one setting at a time. This helps you understand what resolved the issue and avoid retaining unnecessary permissions.

Checklist before handing over a real project

Frequently asked questions

Can I use Codex CLI without a ChatGPT subscription?

You can use an OpenAI API key and pay for the resulting usage. This authentication method does not draw on credits included with a ChatGPT subscription. Access to cloud features may also differ.

Does Codex CLI run entirely on my computer?

Running commands locally does not mean the model runs on your computer. With a hosted model, the information needed to process the task is sent to the service. Check the policies that apply to your account before submitting confidential code.

Can AGENTS.md prevent files from being deleted?

It can explicitly instruct the agent not to delete files, but it does not replace a technical restriction. Protect folders with appropriate permissions and keep an independent backup.

Should I allow every command to avoid interruptions?

A properly defined workspace already allows many actions without interruptions. Expanding all permissions to resolve a single blocked action also exposes files and services unrelated to the task.

Can I use Codex CLI in a continuous integration pipeline?

Yes. The documentation covers programmatic use and recommends API authentication for general automation. Prepare an isolated environment, limit access to secrets, and require independent validation before publishing anything.

Codex CLI reference guide: installation, approvals, sandboxing, AGENTS.md, and costs