OpenAI Codex Cloud Tasks: Running Agentic Coding Jobs Without a Local Machine

Codex cloud tasks are OpenAI's way of running the Codex coding agent in a hosted, sandboxed cloud environment instead of on your laptop. You describe a task, Codex clones your repository into an isolated container, makes the changes, runs your tests, and hands you back a diff and a log you can review before anything touches your real branch. If you have ever wanted to kick off a refactor, a dependency bump, or a bug fix from your phone and come back to a ready-to-review pull request, that is exactly the gap codex cloud tasks fill.

This article walks through what codex cloud tasks actually do under the hood, how to set one up against a real repository, how the sandbox and network access rules work, how to review and merge the output, and where cloud tasks fit next to the local Codex CLI. Everything here assumes you already have an OpenAI account with Codex access and a GitHub (or compatible) repository you can connect.

What codex cloud tasks are and why they exist

The local Codex CLI runs on your machine: it reads your files, executes shell commands, and edits code in your actual working directory. That is great for interactive pairing, but it ties the agent's lifespan to your terminal session and your machine's resources.

Codex cloud tasks solve a different problem: delegation. Instead of watching an agent work in real time, you write a task description, submit it, and walk away. The task runs in a managed cloud container that:

• Clones a snapshot of your connected repository at a specific branch or commit
• Installs dependencies using a setup script you control
• Lets the agent read, edit, and run commands inside that sandbox
• Optionally runs your test suite and lints before finishing
• Produces a diff, a log of every command the agent ran, and (if you enable it) an automatically opened pull request

Because the whole thing runs in an ephemeral, isolated environment, the agent never has direct access to your production credentials, your local filesystem, or any system outside the sandbox unless you explicitly grant it network access. That isolation is the core value proposition: you get agentic coding at cloud scale without giving a model shell access to your real infrastructure.

This matters for a specific set of use cases: batch work you want to fire off in parallel (say, ten independent bug fixes across a monorepo), work you want to kick off from a mobile client or a CI trigger rather than a terminal, and work where you specifically want a sandboxed, reviewable diff rather than live changes to a checked-out branch.

Setting up your first codex cloud task

Before you can run a cloud task, Codex needs a connection to your source control provider and a defined environment for the sandbox.

Connect your repository

In the Codex web interface (or the equivalent panel inside your IDE integration), connect the GitHub organization or account that owns the repository you want to work against. Codex requests read access to clone the repo and, if you want automatic PR creation, write access to open pull requests. Grant access at the repository level rather than organization-wide if you want to keep the blast radius small, especially the first time you try this out.

Define the environment

Every cloud task runs inside an environment, which is essentially a named configuration bundling:

• The base container image (language runtime, OS packages)
• A setup script that runs once when the container boots, before the agent starts working
• Environment variables and secrets the agent is allowed to see
• Network access mode (more on this below)

A typical setup script for a Node.js project looks like this:

#!/usr/bin/env bash
set -euo pipefail

corepack enable
npm ci
npm run build --if-present

For a Python project you might instead have:

#!/usr/bin/env bash
set -euo pipefail

python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-dev.txt

Keep the setup script fast and deterministic. Cache-friendly installs (npm ci over npm install, pinned lockfiles) reduce the time before the agent can actually start working, and a flaky setup script is the single most common reason a cloud task fails before it does anything useful.

Write the task prompt

The task prompt is where you describe the work. Cloud tasks reward the same specificity that makes any coding agent effective: name the files or modules involved, describe the acceptance criteria, and say what "done" looks like. Compare these two prompts:

Fix the flaky test in the checkout flow.

versus:

The test `tests/checkout/test_apply_coupon.py::test_expired_coupon_rejected`
fails intermittently in CI. Investigate whether it's a race condition around
the coupon expiry check in `checkout/coupons.py`. Fix the root cause, not the
test. Run the full checkout test module and confirm it passes 10 times in a
row before finishing. Do not modify unrelated tests.

The second version gives the agent a concrete target, a hypothesis to check, a definition of done, and an explicit boundary. Cloud tasks run unattended, so ambiguity that you'd normally resolve by watching the agent work instead turns into wasted container time or, worse, a plausible-looking diff that doesn't actually fix the problem.

Submit and monitor

Once you submit the task, Codex spins up the container, runs your setup script, and starts the agent loop: read code, plan, edit, run commands, observe results, repeat. You can watch the live log stream in the Codex interface, which shows every command executed and its output, similar to watching a CI job run. If you don't watch live, the task keeps running in the background and you get a notification when it finishes.

How the sandbox and network access work

The sandbox model is the part worth understanding carefully before you rely on cloud tasks for anything sensitive.

By default, the container has no outbound network access once the setup script finishes. This is deliberate: it stops the agent from pulling in surprise dependencies mid-task, phoning home to unexpected endpoints, or exfiltrating anything from your repo. All the dependency installation is expected to happen during the setup phase, when network access is available, not during the agent's editing loop.

If your task genuinely needs network access during the agent phase (hitting an internal API to validate a change, downloading a fixture, etc.), you can allow-list specific domains for that environment. Treat this the same way you'd treat firewall rules for a CI runner: allow only what's needed, and prefer to do data fetching in the setup script wherever possible instead of opening the sandbox up during the agent's free-form execution phase.

Secrets follow the same logic. Anything you add as an environment variable or secret for the environment is available inside the sandbox, so only add credentials the agent actually needs for the task (for example, a read-only API key for running integration tests), not your full deploy credentials. A codex cloud task should never need production write access to do its job; if a task's prompt implies it does, that's a signal to redesign the task rather than widen the sandbox's permissions.

Reviewing and merging the output

When a cloud task finishes, you get three things: a diff, the full command log, and (optionally) a pull request already opened against your repository.

Review the diff exactly as you would review a human contributor's PR: read every changed line, don't assume passing tests mean the change is correct, and pay particular attention to test files the agent may have modified to make a failing test pass rather than fixing the underlying bug. The command log is useful here too. Scan it for signs the agent struggled: repeated failed attempts at the same fix, tests it skipped rather than fixed, or commands that errored and were silently worked around.

If you enabled automatic PR creation, the PR shows up in your normal review queue and you can request changes exactly like any other contribution. If you didn't, you can pull the diff down and apply it locally:

codex cloud diff <task-id> > task.patch
git checkout -b codex/checkout-flaky-fix
git apply task.patch
git status

Run your own test suite locally or in CI before merging, even though the cloud task already ran tests inside its sandbox. The sandbox environment, however carefully configured, is still a different environment from your actual CI, and you want the same gate every other change goes through.

Running multiple cloud tasks in parallel

The place codex cloud tasks earn their keep over the local CLI is fan-out work: independent, well-scoped changes that don't depend on each other. If you're migrating a codebase off a deprecated API across twenty files, you don't need to do that serially in one terminal session. You can submit one task per file or per logical group, each with its own tightly scoped prompt, and let them run concurrently in separate sandboxes.

A practical pattern:

1. Write a short script or spreadsheet listing each independent unit of work (file, module, or ticket)
2. Generate a task prompt per unit using a template that fills in the specific file paths and acceptance criteria
3. Submit all tasks through the Codex API or CLI in a loop
4. Review diffs as they land, merging the clean ones and sending feedback on the rest

This only works well when the units of work are genuinely independent. If two tasks touch overlapping files, you'll get merge conflicts between the resulting PRs, and you'll spend more time reconciling them than you saved by parallelizing. Scope each task narrowly enough that a human reviewer, and the agent itself, can reason about it in isolation.

Cloud tasks versus the local Codex CLI

Both use the same underlying agent, but the operating model differs enough that picking the wrong one for a job costs you time.

Use the local CLI when you want to pair with the agent interactively: you're debugging something ambiguous, the task needs your judgment mid-stream, or you want to steer the approach after seeing the first few edits. Local runs also have direct access to whatever is already set up on your machine: your IDE, your local database, your running dev server.

Use cloud tasks when the work is well-specified enough to hand off completely, when you want to run several jobs at once, when you're kicking off work from somewhere other than your dev machine, or when you specifically want the isolation of a sandboxed diff rather than live edits to your working tree. Cloud tasks are also the natural fit for triggering agentic work from automation: a webhook that opens a cloud task whenever a specific label gets added to an issue, for instance, rather than a human remembering to run a CLI command.

A reasonable default: draft and validate a task's prompt locally on a small example first, confirm the agent's approach is sound, then move the repeatable version of that same task to the cloud for scale.

Common pitfalls

Setup scripts that assume interactive input will hang the container until it times out. Keep every step in the setup script fully non-interactive, and pin dependency versions so a passing task last week doesn't silently break because an upstream package shipped a breaking change.

Vague prompts produce plausible-looking but wrong diffs more often in cloud tasks than in interactive sessions, because there's no human in the loop to redirect the agent when it heads down the wrong path. Front-load the specificity instead of trying to fix it after the fact.

Overly broad repository or secret access defeats the purpose of the sandbox. Grant the narrowest scope that lets the task do its job, and rotate any credentials you add to a shared environment on the same schedule you'd use for a CI service account.

Skipping the command log during review is a missed opportunity. The diff shows you the destination; the log shows you the path the agent took to get there, including any dead ends it papered over.

FAQ

Does a codex cloud task have access to my local machine while it runs? No. The task runs entirely inside a cloud-hosted container against a cloned copy of your repository. It has no access to your local filesystem, processes, or network unless you explicitly connect something during setup.

Can codex cloud tasks open pull requests automatically? Yes, if you grant the connected repository write access and enable automatic PR creation for the environment. Otherwise you can download the diff and apply it manually.

What happens if the setup script fails? The task fails before the agent starts working, and you get the setup log to debug from. No agent time is spent on a broken environment, which is one reason to keep setup scripts simple and deterministic.

Can I run cloud tasks against a private repository? Yes, as long as you grant Codex access to that specific repository through your source control provider's permission model. Private repo access does not change the sandbox's isolation guarantees.

How is network access controlled inside the sandbox? By default the agent's execution phase has no outbound network access after setup completes. You can allow-list specific domains per environment if a task genuinely needs to reach an external service during the agent's editing loop.

Can multiple cloud tasks run at the same time? Yes, and this is the main reason to prefer cloud tasks for large, parallelizable work. Each task gets its own isolated container, so tasks don't interfere with each other as long as they don't target overlapping files.

Do cloud tasks run my test suite automatically? They run whatever your setup script and task prompt tell them to run. If you want tests run before the task is marked complete, say so explicitly in the prompt or bake a test step into the environment configuration, and still re-run your full suite in your own CI before merging.