Codex Cloud Setup: Environments, Cloud Tasks, and the codex cloud CLI

Codex Cloud is OpenAI Codex's hosted execution surface — the openai/codex README states it plainly: if you want the cloud-based agent (called Codex Web in the repo), head to chatgpt.com/codex. Unlike the local CLI, cloud tasks run in a managed environment on a cloud copy of your code, and the result comes back as a diff you pull down locally. This guide is grounded in the openai/codex source at tag rust-v0.156.1 (released 2026-09-23).

1. Where Cloud sits among the three surfaces

Codex ships three working surfaces: the local CLI, the IDE extension, and Codex Cloud. They share the same model and engineering capabilities; what differs is where execution happens — Cloud moves it into a hosted environment, which suits long-running, batch, and unattended work. Surface selection has its own article; this one focuses on Cloud setup and the command surface (see Codex CLI vs IDE Extension vs Codex Cloud: Choosing a Codex Surface).

2. Prerequisites

• A ChatGPT account with Codex access (availability and tier limits are as shown in your account)
• Target code hosted on GitHub — cloud environments are organized per GitHub repo, and CLI-side detection only reads GitHub remotes (see section 3)
• Codex CLI installed and signed in locally (see Getting started with OpenAI Codex CLI: from install to daily use)

3. Environments: organized per GitHub repo

The core Codex Cloud concept is the environment: each one binds to a GitHub repository, and tasks run on a cloud copy of that repo. In the source, environment objects carry id, label, is_pinned, and task_count fields, and a repo can have several environments.

Detection is automatic on the CLI side: codex cloud reads your local git remotes, resolves the GitHub origin into owner/repo, and matches it against the environments configured in the cloud (the source notes this matches the VSCode extension's behavior). Your clone's remote URL decides which environment a task runs in — a fork and its upstream are different environments.

Environment creation happens on the web side at chatgpt.com/codex (exact UI fields as shown in the product). What this article can verify is the mechanism: environments follow the repository, not the directory.

4. The codex cloud command surface (EXPERIMENTAL)

The CLI entry point is codex cloud (alias codex cloud-tasks), marked EXPERIMENTAL in the source — "Browse tasks from Codex Cloud and apply changes locally." Run it bare for the task-browsing TUI (Ctrl+O opens the environment picker):

codex cloud            # task-browsing TUI, Ctrl+O switches environments
codex cloud-tasks      # equivalent alias

Scripted use goes through five subcommands:

exec has three flags worth knowing (defined in cli.rs):

codex cloud exec "add form validation to the login page" --env env_xxx --attempts 2 --branch main

• --env ENV_ID: required. The target environment ID — browseable in the TUI (the flag help literally says: see codex cloud to browse)
• --attempts N: best-of-N, accepting 1 through 4, default 1 — run the task several times and pick among results
• --branch BRANCH: which branch runs in the cloud; defaults to your current branch

Tracking and collecting a submitted task:

codex cloud list --env env_xxx --json   # list tasks (--limit 1-20, --cursor pagination)
codex cloud status <task-id>            # single-task status
codex cloud diff <task-id>              # view the patch; with best-of-N use --attempt 2
codex cloud apply <task-id> --attempt 1 # land the chosen attempt's diff locally

5. Suggested workflow

1. Create an environment for the target repo on the web side (as shown in the product)
2. Run codex cloud locally and confirm the environment is autodetected
3. Start with a single exec run (default --attempts 1); use best-of-N when the solution space is wide
4. When it finishes, review with codex cloud diff, then codex cloud apply to land it — cloud output gets the same human review as local output
5. If a task misbehaves, check the Codex Web component on status.openai.com first (it is a standalone entry in the official component list), then verify your git remote and environment ID

6. Common errors and troubleshooting

• No environment detected: check that the git remote is a GitHub URL (detection only reads GitHub origins) and that a cloud environment exists for the repo
• exec argument errors: --attempts only accepts 1-4; --env is required and must be a real environment ID
• Task stuck: check the Codex Web status component first, then confirm the branch exists in the cloud repo
• apply conflicts: the cloud result is a patch; if local edits touched the same regions while the task ran, resolving overlaps is manual after apply

7. Next steps

• Codex CLI vs IDE Extension vs Codex Cloud: Choosing a Codex Surface — when a task belongs in the cloud
• Codex CLI config.toml: The Complete Guide to Models, Approvals, MCP and Layered Config — the local side of configuration
• Getting started with OpenAI Codex CLI: from install to daily use — install and sign-in