One Codex, Many Surfaces

The single most useful idea in this lesson: there is one Codex. It is not a CLI plus a separate web app plus a separate phone app that happen to share a brand. It is one agent, backed by one model family, tied to one ChatGPT account, that you reach through different surfaces — the terminal, your editor, the cloud, a desktop app, your phone, GitHub, and the API.

Think of it like your email. Gmail in the browser, the iPhone Mail app, and a desktop client are different windows into the same mailbox — send from one, see it in another. Codex is the same: start a task in your editor, monitor it from your phone, review the resulting pull request on GitHub. The account is the thread that ties them together.

That framing pays off immediately, because it tells you what transfers across surfaces and what doesn't:

• What transfers: your AGENTS.md instructions, your config.toml, your MCP server connections, and your session history. Configure a project once and every surface honors the same rules.
• What differs: where the agent runs (your machine vs. an OpenAI sandbox) and what's convenient (a phone is great for monitoring, a terminal is great for tight local edits).

So this lesson is really a tour of windows into one room — and a guide to which window to stand at for which job.

Local surfaces run the agent on your machine, in your working directory, with your files and your tools. There are three.

1. Codex CLI — the canonical surface. An open-source terminal agent written in Rust that runs locally on macOS (Apple Silicon + Intel), Linux (x86_64 + arm64), and Windows (native sandbox or WSL2). Run codex in a project directory and you get a full-screen TUI where the agent inspects the repo, proposes changes, and pauses for approval. It reads, edits, and runs code right on your machine.

2. IDE extension — Codex inside your editor. It supports VS Code (and Insiders), the VS Code-compatible forks Cursor and Windsurf, and JetBrains IDEs (IntelliJ, PyCharm, WebStorm, Rider). The extension id is openai.chatgpt. You get a model selector, @filename references, and open files/selection as context — and crucially, the IDE can delegate work to Codex Cloud and apply the resulting diffs back locally (more on that below).

3. Desktop app — a standalone Codex app for macOS and Windows with a project sidebar, thread management, review tools, an in-app browser, and Computer Use support. Launch it from the terminal with codex app. It shows your past projects from the CLI, IDE, and cloud — shared history in action.

All three sign in with the same ChatGPT account (or an API key) and read the same AGENTS.md and config.toml.

Codex cloud (a.k.a. Codex Web) lives inside the ChatGPT web app at chatgpt.com/codex. Instead of running on your machine, each task runs in its own isolated OpenAI sandbox container, checked out at a branch or commit of a GitHub-connected repo. Two properties make the cloud worth reaching for:

• Background + parallel. You can fire off several tasks at once and walk away; they run in their own environments while you do other things. The cloud is the surface for "go work on these three issues while I'm in a meeting."
• It opens pull requests. When a cloud task finishes, Codex creates a PR in the connected repo. You review the diff in the cloud diff view, or git fetch/git checkout to test locally before merging.

A few details that matter for safety and reliability:

• Internet access is OFF by default during the agent phase. Setup scripts (which install dependencies) keep it ON, then it's locked down; you can re-enable network access for the agent by domain allowlist if you need it.
• Secrets exist only during setup and are removed before the agent phase runs — so a prompt-injected agent can't read your deploy keys.
• Environments use a base image and cache state for a limited window, auto-installing npm/pip/poetry/etc. dependencies.

You can reach the cloud from many places: the web UI, the IDE's "Run in the cloud," GitHub @codex, mobile, and the CLI's codex cloud command.

# Delegate a task to the cloud from the terminal
codex cloud exec --env ENV_ID "fix the failing CI on the billing module"
codex cloud list --env ENV_ID --limit 10   # see your cloud tasks

Mobile is the surprising one. Codex on your phone (inside the ChatGPT iOS/Android app) is not running the agent on the phone — your phone is a remote control for a Codex environment running somewhere else: your Mac, a Windows machine, or a cloud space.

How it works, and why it's safe:

• You pair the phone to a host by scanning a QR code that Codex for Mac/Windows displays.
• A secure relay layer keeps trusted machines reachable across devices without exposing them directly to the public internet.
• Files, credentials, and permissions stay on the host machine. The phone sends instructions and shows you progress and diffs; it never holds your repo or secrets.

That remote-control idea is the same trick that powers the local↔cloud handoff — the feature that makes "one Codex" tangible:

1. From the IDE or CLI, choose "Run in the cloud" / codex cloud to delegate a task. It runs in the background in an OpenAI sandbox while you keep working.
2. You monitor it from anywhere — the IDE, the web, or your phone.
3. When it's done, bring the diff back local with codex apply TASK_ID (alias codex a) and review/commit it on your machine.

  Local (CLI / IDE)                Cloud sandbox
  ─────────────────                ─────────────
  "Run in the cloud"  ──delegate──▶  agent works in background
        ▲                                  │
        │   monitor from phone / web / IDE  │
        │                                  ▼
  codex apply TASK_ID  ◀──diff back──   proposes changes / PR

Because it's all one account, the task you started in your editor is the same task you watch from your phone and the same diff you apply at your desk.

Beyond the interactive surfaces, Codex shows up in two more places that matter for teams and automation.

GitHub. Codex does automated code review and runs cloud tasks from a repo:

• Enable Code review for a repo in Codex settings (and optionally Automatic reviews to review every new PR).
• Trigger a review manually by commenting @codex review on a PR — the bot reacts with 👀, then posts a standard GitHub review flagging only serious (P0/P1) issues. You can scope it: @codex review for security regressions.
• Ask for fixes: @codex fix it (or @codex fix the P1 issue) spins up a cloud task that pushes fixes to the branch.
• Review priorities follow a ## Review guidelines section in the closest AGENTS.md to each changed file — the same instruction file your local agent reads.

The OpenAI API + Codex SDK. The Codex models are available directly via the OpenAI Responses API (the gpt-5.x-codex line), and a Codex SDK (TypeScript @openai/codex-sdk and Python openai-codex) embeds the agent into your own automations and CI. Under the hood the SDK drives the same CLI agent, exchanging structured events — so a code-review bot you build with the SDK behaves like the agent you use interactively.

Note that some surfaces evolve — Codex models are also offered via Azure OpenAI / Microsoft Foundry and Amazon Bedrock, and whether Slack remains a supported surface is the kind of detail that shifts. Confirm the current surface list at the docs home rather than trusting a snapshot.

Two facts cement "one Codex" and then point you to the right surface for a job.

One account ties it together. A single ChatGPT login spans the CLI, IDE, desktop app, web, mobile, and the GitHub bot. Past projects from the app, CLI, and IDE show up across surfaces; a task delegated from local runs in the cloud and its diff comes back to your machine. Sign-in is either your ChatGPT account (bundled plan usage, simplest, full-featured) or an OpenAI API key (usage-based billing, good for headless/CI — with a few plan-only features gated).

One usage window. Because it's literally one metered product, local messages and cloud tasks share the same rolling 5-hour usage window, plus additional weekly limits. Burning through cloud tasks eats into your local budget and vice versa — they draw from the same pool. (The exact per-plan numbers and the weekly caps are volatile; check the live pricing/usage pages.)

Now the practical payoff — a rule of thumb for picking a surface:

The surfaces aren't competitors — they're the same agent positioned for different moments in your day.