Codex Cloud Environment Setup Guide

Codex Cloud tasks are only as reliable as the environment they run in. If dependencies are missing, package versions drift, test commands are undocumented, or secrets are handled carelessly, the agent may spend most of its time fighting setup instead of solving the task.

This guide explains how to set up a practical Codex Cloud environment: package installs, setup scripts, maintenance scripts, environment variables, secrets, cache resets, internet access, and repository guidance.

Quick Answer

Create a Codex Cloud environment before you delegate serious work. Start with automatic setup if your project uses common package managers. Add a manual setup script when the project needs extra tools, multiple package installs, generated files, or build steps.

Put durable project instructions in AGENTS.md: package manager, setup commands, lint commands, test commands, build commands, and directories Codex should avoid. Use secrets only for setup scripts because secrets are removed before the agent phase. Reset the environment cache when setup changes.

What Happens During A Cloud Task

The official Codex Cloud environment flow has a predictable shape:

1. Codex creates a container.
2. It checks out your repository at the selected branch or commit.
3. It runs your setup script.
4. It may run a maintenance script when resuming a cached container.
5. It applies your internet access settings.
6. The agent edits code, runs commands, and validates work.
7. It returns an answer and a diff.
8. You can open a pull request or ask follow-up questions.

That means environment setup is not background decoration. It is the first part of every cloud task.

Start With The Universal Image

Codex Cloud uses a default container image with common languages, packages, and tools. For many repositories, that is enough to start. If your project depends on specific runtime versions, use environment settings to pin versions for languages such as Node.js or Python.

Use the default image when:

1. The project uses standard package managers.
2. Dependencies install cleanly.
3. Tests can run without private services.
4. Runtime version requirements are flexible or documented.

Add manual setup when:

1. You need extra system packages.
2. You need multiple package managers.
3. You need generated code before tests.
4. You need a local service or tool.
5. Automatic setup misses a project-specific command.

Automatic Setup

Automatic setup can install dependencies for common ecosystems such as npm, yarn, pnpm, pip, pipenv, and poetry.

Use automatic setup first for simple repositories. Then run a small cloud task that only asks Codex to inspect the project and run the main checks:

Verify that this repository environment is ready. Do not edit files. Identify the package manager, install state, lint command, test command, and build command. Run the safest available check and report any setup issue.

If Codex cannot find the right commands, do not solve that with a longer prompt every time. Add the commands to AGENTS.md.

Manual Setup Script

Use a setup script when the repository needs explicit preparation. Examples:

pnpm install
pnpm build

pip install pyright
poetry install --with test
pnpm install

Keep setup scripts deterministic. Avoid interactive prompts. Avoid writing machine-specific paths. Avoid depending on files that are not committed or provided through environment settings.

One subtle detail matters: setup scripts run in a separate Bash session from the agent. A plain export FOO=bar in setup does not automatically persist into the agent phase. If a value must persist, configure it as an environment variable or write appropriate shell initialization.

Maintenance Script And Cache

Codex caches container state to speed up future tasks and follow-ups. That is good for speed, but it can surprise you when dependencies change.

Use a maintenance script when a cached container needs lightweight refresh work, such as:

pnpm install --frozen-lockfile

Reset the cache when:

1. The setup script changes.
2. Runtime versions change.
3. Lockfiles change in a way that breaks cached dependencies.
4. Generated files are stale.
5. Codex repeatedly reports setup issues that should already be fixed.

For Business and Enterprise workspaces, shared cache behavior can affect teammates who use the same environment. Treat cache resets as a workspace-level action, not just a personal preference.

Environment Variables And Secrets

Environment variables are available for the full task, including setup and the agent phase. Secrets are more restricted. They are encrypted and only available to setup scripts; for security, they are removed before the agent phase.

Use environment variables for non-sensitive configuration:

1. Feature flags for tests.
2. Local test endpoints.
3. Safe public configuration.
4. Build mode settings.

Use secrets only when setup truly needs them:

1. Private package registry tokens.
2. Private dependency access.
3. Temporary credentials for installing tools.

Do not design a cloud task that requires the agent to read production secrets. If the agent needs live production credentials to complete the task, the task is probably too risky for a general coding agent workflow.

Internet Access

Setup scripts can use internet access to install dependencies. During the agent phase, internet access is off by default unless you configure limited or unrestricted access.

Keep agent internet access off for most code tasks. Turn it on only when the task genuinely needs current external documentation, package metadata, or a controlled network target. If you enable it, prefer limited access to specific domains rather than unrestricted access.

For local and CI automation risk patterns, see the Codex Permissions and Sandbox Guide.

Add AGENTS.md

AGENTS.md is the most important file for repeatable cloud tasks. It tells Codex how the repository works without forcing you to repeat the same setup details in every prompt.

Include:

1. Package manager.
2. Install command.
3. Dev server command.
4. Lint command.
5. Type-check command.
6. Test command.
7. Build command.
8. Paths to avoid.
9. Deployment boundaries.
10. Review expectations.

Example:

# AGENTS.md

Use pnpm.

Common commands:
- pnpm install
- pnpm lint
- pnpm test
- pnpm build

Before finishing a code change, run the closest relevant test. For UI changes,
also check that mobile layout has no document-level horizontal scroll.

Do not edit generated files in .next, dist, coverage, or node_modules.

For a deeper template, see the Codex AGENTS.md Guide.

First Cloud Task To Run

After setting up the environment, run a no-edit smoke test:

Do not edit files. Inspect this repository and verify the cloud environment. Identify the package manager, setup status, lint command, test command, build command, and any missing dependency or environment variable. Run one safe check if available.

Then run a small edit task:

Fix one failing test related to the smallest reproducible failure. Keep the patch minimal, run the specific test, and explain any test that could not be run.

If the first edit task fails because setup is incomplete, fix the environment before sending more feature work.

IDE Delegation

The Codex IDE Extension Tutorial covers cloud delegation from an editor. The same environment principles apply. A task started from the IDE can preserve conversation context, but the cloud runner still needs dependencies, scripts, and repository rules.

Use cloud delegation when:

1. The task is larger than a quick local edit.
2. You want work to continue while you do something else.
3. The repository can build and test in the cloud.
4. The task does not depend on a local-only service.

Stay local when the task depends on screenshots, local browser state, private local files, or a running service that does not exist in the cloud environment.

Common Environment Mistakes

The first mistake is assuming the cloud runner has the same state as your laptop. It does not. If a generated file, local dependency, or environment variable is required, make it reproducible.

The second mistake is hiding setup knowledge in prompts. Put durable commands in AGENTS.md or the environment setup script.

The third mistake is giving internet access to the agent phase without a reason. Most code tasks only need repository files and package scripts.

The fourth mistake is using secrets as if they were runtime variables for the agent. Secrets are designed for setup, not for arbitrary agent use.

The fifth mistake is ignoring cache. If a task keeps failing after setup changes, reset the cache before assuming Codex misunderstood the code.

Best Setup Checklist

Before asking Codex Cloud for serious work, confirm:

1. The repository checks out cleanly.
2. Dependency installation is deterministic.
3. Runtime versions are pinned when needed.
4. Setup script completes without interaction.
5. Maintenance script handles cached updates.
6. AGENTS.md documents commands and constraints.
7. Secrets are limited to setup.
8. Agent internet access is off or narrowly scoped.
9. A no-edit environment smoke test passes.
10. The first edit task is small and reviewable.

Once those basics are in place, cloud tasks become much more useful. Codex can spend its time solving the engineering problem instead of guessing how your project is supposed to run.

Related Codex Tutorials

• Codex Cloud Tasks Guide
• Codex IDE Extension Tutorial
• Codex AGENTS.md Guide
• Codex Permissions and Sandbox Guide
• Codex Exec Automation Guide
• Codex GitHub Action Tutorial
• Codex CLI Tutorial
• Codex vs Claude Code

Official References

• Codex cloud environments
• Codex cloud internet access
• Codex AGENTS.md guidance
• Codex agent approvals and security
• Codex web