Codex CLI installation guide: local machines, dev containers, and CI

Quick answer: one binary, one config file, different auth per environment.

Codex CLI installs the same way on every machine: run npm install -g @openai/codex, or use the Homebrew formula or a downloaded binary release if you would rather not put a Node toolchain on the box, and you end up with one executable. What actually differs between a laptop, a dev container, and a CI runner is not the install step, it is which model answers, how the agent authenticates, and how much of the filesystem it is allowed to touch, and all three of those live in a single config.toml under ~/.codex/. On a local machine, most people run codex login once, let the CLI hold onto a browser-based ChatGPT sign-in, and approve or deny each command as the agent proposes it. A dev container or a CI runner usually has no browser and no human watching the terminal, so both authenticate with an API key read from an environment variable and both drive Codex through its non-interactive codex exec mode instead of the normal chat session. The install command never changes; the config and the auth path do.

How Codex CLI finds its model and your key.

Every time Codex CLI starts a task, it resolves three things before sending a single token: which provider to call, which model at that provider to use, and where to read the credential for that provider. All three come from config.toml, or from a named profile inside it that a --profile flag switches to, and none of them are hard-coded into the binary you installed. The provider setting is what makes container and CI setups possible in the first place. A model_providers.<name> block just needs a name, a base_url, and the name of the environment variable holding the key, and Codex calls it exactly like the built-in OpenAI provider. That is also the mechanism for routing to a different, OpenAI-compatible model without touching any application code, since Codex only cares that the endpoint speaks the same wire format. Two other keys, approval_policy and sandbox_mode, are unrelated to which model answers, and they are the ones that matter most once you leave a laptop. On-request approval with a workspace-write sandbox is the sane interactive default. Full autonomy with a wide-open sandbox is a different story: it is reasonable inside a disposable container built for exactly that job, and it is a bad idea on a machine with your real filesystem underneath it.

What a week of CI runs actually costs.

Model the cost the same way you would model any other metered CI step: tokens per run, times runs per week. A lint or format-fix job on a small diff reads little and writes little. A full PR-review job that pulls in the diff, a couple of surrounding files, and test output is the common case. A nightly regression-triage job that pulls in many failing tests at once is the expensive tail. The table below prices all three at three model tiers, in dollars per run: gpt-5.3-codex-spark as the codex-tuned default, gpt-5.5 as a heavier general model some teams reserve for hard cases, and deepseek-v4-pro as a budget model reachable through a custom provider entry for steps that do not need either.

Why installs and auth break in containers and CI.

Most Codex CLI failures outside a local terminal trace back to one of these five, and the error message rarely names the real cause directly, so it is worth checking PATH, the env_key name, and the approval and sandbox settings before assuming the model or the key itself is at fault.

• The ChatGPT sign-in flow needs a browser and a callback; it hangs or times out on a headless server or a CI runner with no display, which is why CI has to use an API key from the start rather than falling back to it after login fails.
• A global npm install lands in a user-specific prefix, and a slim base image built for a devcontainer or a fresh CI runner often puts that prefix somewhere that is not on PATH inside the container, so the very next command fails with "not found" even though the install step reported success.
• Full autonomy with a wide-open sandbox executes shell commands with no per-step approval; running that mode directly on a laptop is asking for trouble, which is exactly why dev containers exist, to give full autonomy a disposable filesystem instead of your real one.
• A config.toml checked into a shared devcontainer image can name an env_key that does not match the secret name in a different CI system, which produces an authentication error that looks like a bad key when the actual problem is a mismatched variable name.
• Several CI jobs pointed at the same API key can trip per-key rate limits when several checks fire on the same push, which shows up as an intermittent failure on one job rather than a clean, obvious error.

Local install vs dev container vs CI runner.

The binary is identical across all three. What changes is how Codex authenticates and how much it is trusted to do without asking first.

Practical fixes for containerized and CI installs.

None of these fixes require a different install method. They are config, secrets, and caching decisions layered on top of the same executable you already installed.

• Pin the Node or runtime version in devcontainer.json and in the CI workflow instead of trusting whatever the base image ships, so an install that works today does not silently change under a base image update.
• Set the API key as an environment variable in the CI secret store rather than baking it into a committed config.toml, and reference it by name in the matching model_providers.<name>.env_key field.
• Use codex exec in CI instead of trying to script the interactive session; it is built for one-shot, log-friendly runs with no terminal attached and a clean exit code at the end.
• Build the devcontainer from a minimal, disposable image and mount only the repository path, then treat that isolation, not the CLI's own confirmation prompts, as the actual safety mechanism when full autonomy is enabled.
• Cache the install step in CI, either an npm cache or a prebaked devcontainer image, so every job is not repeating a fresh download and version resolution on top of the model call itself.
• If a repetitive step, like lint fixes or boilerplate test generation, is running often enough to show up on the bill, give it its own model_provider profile pointed at a lower-priced OpenAI-compatible endpoint, and keep the flagship codex model for the steps that actually need its judgment.

Config file and CI workflow example.

The model_providers table in config.toml is the extension point for all of this: give a provider a name, a base_url, and the environment variable holding its key, and Codex calls it the same way it calls the built-in OpenAI provider. Below is a config.toml with the default provider, a second provider named APIsRouter pointed at an OpenAI-compatible endpoint, and a profile that a CI job can select without touching the rest of the file. A custom provider is not limited to OpenAI models either; the same block works for a budget option like kimi-k2.7-code or deepseek-v4-pro if that is what a given profile should call. The workflow snippet after it installs Codex, exports the key from a repository secret, and runs one headless PR-review task using that profile.

model_provider = "openai"
model = "gpt-5.3-codex-spark"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[model_providers.keaiapi]
name = "keaiapi"
base_url = "https://api.apisrouter.com/v1"
env_key = "KEAIAPI_API_KEY"
wire_api = "chat"

[profiles.ci-bulk]
model_provider = "keaiapi"
model = "deepseek-v4-pro"
approval_policy = "never"
sandbox_mode = "danger-full-access"

FAQ