Codex local vs cloud workflows: when to delegate tasks

“Local or cloud?” is too simple a question for current Codex workflows. There are three useful execution patterns:

1. Direct local work in the current checkout through the CLI or IDE.
2. Local worktrees created by the ChatGPT desktop app with a configured local environment.
3. Cloud tasks that run in a remote container at a selected branch or commit.

Choose among them based on where the required state exists, how much isolation the task needs, and how the result will be reviewed.

The short decision rule

• Use the current local checkout for immediate, interactive work that depends on local state.
• Use a local worktree when you want isolation but still need your machine, tools, and local feedback loop.
• Use a cloud task when the task can be reproduced from repository state and should run separately in a prepared remote environment.

Do not send a task to the cloud just because it is long. Send it when the inputs and verification can travel with it.

Comparison

Direct local work

Direct local work is the right default when:

• the bug is already reproduced on your machine;
• the task depends on uncommitted changes;
• a local database, simulator, device, or service is required;
• you need to watch the command output and steer frequently;
• data should remain in the local environment.

The CLI and IDE can inspect files, edit, run commands, and review changes against the active checkout. This speed is valuable, but the task shares the current working tree. Check Git status before starting and preserve unrelated edits.

Use a read-only sandbox for investigation or a workspace-write sandbox for normal implementation. The approval and sandbox guide explains how those boundaries differ from execution location.

Local worktrees

The ChatGPT desktop app can create separate local worktrees. The official local environment documentation lets a project define:

• setup steps that run when a worktree is created;
• common actions such as starting the app or running tests;
• platform-specific variants where needed.

A worktree is useful when:

• you want parallel feature work without mixing diffs;
• the task needs local tools or services;
• the repository setup can be repeated;
• a clean branch boundary matters.

It does not automatically copy ignored files, local databases, or every environment value. The setup script must recreate the required development state safely.

Cloud tasks

A Codex cloud task starts from repository state, not the live contents of your laptop.

The current cloud environment documentation describes this sequence:

1. create a container and check out the selected branch or commit;
2. run a setup script, plus an optional maintenance script for a resumed cache;
3. apply internet-access settings;
4. let the agent edit and validate;
5. return a summary and diff for review.

This is a good fit for:

• a scoped change with deterministic setup;
• test repair or dependency work;
• repository-wide analysis;
• an isolated reproduction;
• a task you want to review later as a diff or pull request.

Cloud is a poor fit when the task depends on uncommitted local files, a hardware device, a private local service, or credentials that should not be available remotely.

Setup scripts are part of the product

If a cloud or worktree task cannot install dependencies and run the relevant test, the environment is not ready.

A useful setup script:

• is deterministic;
• uses the repository’s actual package manager;
• installs only required tools;
• fails clearly;
• does not print secrets;
• is fast enough for repeated use.

Cloud environments can automatically install common package-manager dependencies, or you can provide custom setup. Setup runs separately from the agent phase, so an export in the setup shell does not automatically persist as agent environment state.

Secrets and environment variables

Cloud environment variables are available throughout the chat. Managed secrets have a narrower lifecycle: the current documentation says they are decrypted for task execution, available to setup scripts, and removed before the agent phase.

That design means a package install can use a private registry credential without handing the same secret to every generated command.

Still apply least privilege:

• provide only secrets the setup actually needs;
• prefer scoped, revocable credentials;
• do not place production secrets in repository files;
• keep generated diagnostics private when they contain environment details.

Internet access

Cloud setup scripts can use the internet to install dependencies. During the agent phase, internet access is off by default and can be configured as limited or unrestricted.

This distinction matters. A successful dependency install does not prove the agent can later call an external API. Conversely, enabling unrestricted agent access changes the task’s security boundary.

Choose the narrowest network policy that supports the task.

Context does not transfer magically

Cloud tasks know the repository state they checked out plus the prompt and configured environment. They do not automatically receive:

• uncommitted local edits;
• ignored files;
• an open editor selection;
• a local database snapshot;
• shell aliases;
• a service running only on your machine.

Before delegation, ask:

1. Is every required input committed or reproducible?
2. Can setup create the needed environment?
3. Can the result be verified without my local-only state?
4. Is the target branch or commit explicit?

If any answer is no, keep the task local or package the missing input safely.

A hybrid workflow that works

1. Reproduce locally

Confirm the failure and identify the focused test or command.

2. Make the task portable

Commit or otherwise provide the necessary repository state. Ensure setup can run the test.

3. Delegate the bounded change

Specify the branch or commit, expected behavior, allowed scope, and verification command.

4. Review the returned diff

Read the summary, inspect every changed file, and check that the expected test actually ran.

5. Verify in the destination environment

Run the relevant checks again where the change will be integrated. Remote success does not replace branch integration testing.

Examples

Keep local: UI bug with local backend state

The bug depends on a database record and a service running on your machine. Direct local work provides the fastest feedback and avoids exporting sensitive state.

Use a worktree: parallel dependency upgrade

The upgrade needs local package caches and browser checks, but should not contaminate the active feature branch. A local worktree gives isolation without losing local tooling.

Use cloud: repository-wide test migration

The task is reproducible from a commit, setup can install dependencies, and the expected test suite is documented. Cloud execution can run independently and return a reviewable diff.

Do not delegate yet: uncommitted prototype

The task references files that exist only in the current checkout. First decide whether to commit them, create a local worktree from the state, or continue in place.

Operational safeguards

• Fetch and inspect branch state before delegation.
• Name the intended base branch or commit.
• Keep AGENTS.md current and concise.
• Do not assume cloud caches reflect the latest dependency state.
• Reset the cloud cache when setup or environment changes make it incompatible.
• Review all diffs before merging.
• Rerun integration checks on the destination branch.

Related guides

• Codex CLI and VS Code integration
• Codex approval policies and sandbox modes
• Troubleshooting Codex in VS Code

The best environment is the one that has the necessary inputs, the smallest reasonable blast radius, and a clear path from generated work to verified code.