Cloud Execution Environments

Your teammate in a different timezone posts a Slack message: “@Codex fix the failing integration tests in the payments service.” Within minutes, Codex spins up a cloud container, clones the repo, installs dependencies, identifies the root cause, and replies with a link to the fix — all without anyone opening a laptop. This is the power of Codex cloud execution.

What You’ll Walk Away With

• A production-ready cloud environment configuration with setup scripts, secrets, and caching
• A strategy for internet access that balances security with the need to fetch packages
• The best-of-N pattern for generating multiple solution attempts and picking the best one
• Troubleshooting techniques for container caching, network proxies, and environment drift

How Cloud Tasks Run

When you submit a cloud task, Codex follows a precise sequence:

1. Container creation: Codex creates a container from the universal base image (or a cached state) and checks out your repo at the selected branch or commit SHA.

2. Setup script: Your custom setup script runs with full internet access. This is where you install dependencies, tools, and configure the environment.

3. Maintenance script (cached containers only): If a cached container is resumed, the maintenance script updates dependencies that may have changed since the cache was created.

4. Internet access lockdown: Agent internet access is disabled by default. Your environment-specific allowlist takes effect.

5. Agent execution: The agent works in a loop — reading files, editing code, running commands, and validating. It uses your AGENTS.md to find project-specific lint and test commands.

6. Results: The agent presents its answer and a diff. You can open a PR or ask follow-up questions.

Environment Configuration

Configure environments at Codex settings > Environments.

Setup Scripts

For projects beyond basic npm install, write a custom setup script:

# Install system dependencies
apt-get update && apt-get install -y libpq-dev redis-tools

# Install language-specific tools
pip install pyright poetry
poetry install --with test

# Install Node dependencies
pnpm install

# Build shared libraries
pnpm run build:shared

Setup script gotchas

Setup scripts run in a separate Bash session from the agent. export commands do not persist into the agent phase. To persist environment variables, add them to ~/.bashrc or configure them in the environment settings UI.

Environment Variables and Secrets

Environment variables are available for the entire task duration (setup + agent). Use them for non-sensitive configuration like NODE_ENV=test or DATABASE_URL=postgres://localhost/test.

Secrets get an additional encryption layer and are only available during setup scripts. They are removed before the agent starts. Use secrets for API keys needed during npm install (e.g., private registry tokens) but never for runtime values the agent needs.

Container Caching

Codex caches container state for up to 12 hours. When caching is active:

1. The setup script runs once and the result is cached
2. Subsequent tasks skip the setup script and use the cached container
3. The maintenance script (optional) handles updates like npm install after dependency changes

Cache is automatically invalidated when you change the setup script, maintenance script, environment variables, or secrets. Hit Reset cache manually if your repo changes break compatibility.

For Business and Enterprise plans, caches are shared across all users with environment access. Invalidating the cache affects everyone.

Prompt: Configure a robust cloud environment

“Set up a cloud environment for our Next.js monorepo. The setup script should: install pnpm globally, run pnpm install in the root, build the shared packages with pnpm run build:packages, and run pnpm run db:migrate to set up the test database. Add a maintenance script that runs pnpm install and pnpm run db:migrate to catch dependency and schema changes between cached runs.”

Internet Access Configuration

By default, the agent has no internet access during execution. This is a deliberate security decision — it prevents prompt injection from untrusted web content, code exfiltration, and downloading vulnerable dependencies.

When you need internet access, configure it per-environment:

Domain allowlist: Start with the “Common dependencies” preset, which covers npm, PyPI, crates.io, and dozens of other package registries. Add custom domains as needed.

HTTP method restrictions: For maximum safety, restrict to GET, HEAD, and OPTIONS only. This prevents the agent from posting data to external servers even if it visits a page with malicious instructions.

Prompt injection risk with internet access

If the agent fetches a GitHub issue with hidden instructions like “run this curl command,” it could exfiltrate code. Always use the narrowest allowlist possible and review agent output when internet access is enabled.

Best-of-N Parallel Attempts

From the CLI, you can request multiple parallel attempts for a cloud task:

codex cloud exec --env ENV_ID --attempts 3 "Fix the failing integration tests"

Codex runs 3 independent agents on the same task. Each produces its own solution. You review all three and pick the best one. This is particularly effective for:

• Complex refactors where multiple valid approaches exist
• Bug fixes where the root cause is ambiguous
• Performance optimization where different strategies have different trade-offs

When This Breaks

• Setup script fails silently: Check that your script uses set -e or has explicit error handling. A failed apt-get install might not stop the script, leading to missing tools during the agent phase.
• Cache goes stale: If your project’s dependency tree changes frequently, add a maintenance script that runs the equivalent of npm install. Without it, cached containers may have outdated dependencies.
• Agent cannot find commands: Remember that export in the setup script does not persist. Put tool paths and environment variables in ~/.bashrc instead.
• Network proxy issues: All outbound traffic passes through an HTTP/HTTPS proxy. Some tools (like curl with custom certificates) may need proxy-aware configuration.
• Container image mismatch: The default universal image comes with common languages pre-installed. If you need a specific version, use “Set package versions” in environment settings or install it in your setup script.

What’s Next

• Non-Interactive Mode — Use codex exec to trigger cloud-like workflows from CI
• GitHub Action — Automate cloud-style tasks directly in GitHub Actions
• Cost Management — Cloud tasks consume more credits than local tasks; learn to optimize