Cloud Environment Tips

You submitted a cloud task and it took twelve minutes because Codex spent eight of them running npm install. The next task failed because it could not reach an external API that your tests depend on. Cloud tasks are powerful — they run in isolated containers, produce clean diffs, and support parallel attempts — but only when the environment is configured correctly. A well-tuned cloud environment makes the difference between a task that finishes in four minutes and one that times out.

What You’ll Walk Away With

• Environment setup patterns that minimize cold-start time
• Container caching strategies that keep your environment warm
• Internet access configurations for different security postures
• Best-of-N techniques that maximize solution quality for critical tasks
• CLI workflows for submitting and managing cloud tasks efficiently

Environment Setup

Automatic vs. Manual Setup

Codex offers two setup paths:

• Automatic: Codex detects common package managers (npm, yarn, pnpm, pip, pipenv, poetry) and installs dependencies automatically
• Manual: You provide a custom setup script for complex environments

For most projects, start with automatic setup and add a manual script only when Codex misses something.

Writing an Effective Setup Script

# Install system dependencies
apt-get update && apt-get install -y postgresql-client redis-tools

# Install project dependencies
pnpm install --frozen-lockfile

# Install dev tools the agent might need
pip install pyright ruff

# Build any generated code
pnpm run codegen

# Verify the environment works
pnpm run type-check

Key principles:

• Use lockfiles (--frozen-lockfile, --no-update) to ensure reproducible installs
• Install dev tools the agent will need for linting, type-checking, and testing
• Run a verification step at the end so failures are caught during setup, not during the task

Persist Environment Variables

Setup scripts run in a separate Bash session from the agent. export does not carry over. Instead:

# Wrong: this won't persist
export DATABASE_URL="postgresql://localhost:5432/test"

# Right: write to .bashrc
echo 'export DATABASE_URL="postgresql://localhost:5432/test"' >> ~/.bashrc

Or better, configure environment variables in the Codex settings UI so they are set for the full task duration.

Prompt: Debug a cloud environment setup

“My Codex Cloud task failed during setup with this error: [paste error] The setup script installs dependencies with pnpm and runs codegen. Diagnose why the setup failed and suggest a fix for the setup script.”

Maintenance Scripts

When container caching is active, the agent resumes from a cached state that may be based on an older commit. Use a maintenance script to keep dependencies current:

# Fetch latest changes
git fetch origin

# Update dependencies if lockfile changed
pnpm install --frozen-lockfile

# Re-run codegen in case schemas changed
pnpm run codegen

The maintenance script runs every time a cached container is resumed, so keep it fast.

Container Caching

How Caching Works

1. Codex clones the repository and runs the setup script
2. The resulting container state is cached for up to 12 hours
3. Future tasks resume from the cached state, skipping the full setup
4. The maintenance script runs on resume to handle dependency changes

Cache Invalidation

The cache invalidates automatically when you change:

• The setup script
• The maintenance script
• Environment variables
• Secrets

If your repository changes in a way that makes the cached state incompatible (e.g., a major dependency upgrade), manually reset the cache from the environment settings page.

Optimize for Cache Hits

Structure your setup script so the expensive parts (system packages, large dependency installs) come first and change infrequently. Put volatile steps (codegen, schema updates) in the maintenance script.

# Setup script: expensive, rarely changes
apt-get update && apt-get install -y build-essential
pnpm install --frozen-lockfile

# Maintenance script: cheap, runs every time
pnpm install --frozen-lockfile  # handles lockfile drifts
pnpm run codegen

Shared Caches for Teams

For Business and Enterprise users, caches are shared across all users who have access to the environment. One team member’s setup benefits everyone. Be aware that resetting the cache affects all users.

Internet Access

The Three Levels

Level	Description	Use Case
Off (default)	No internet during agent phase	Maximum security, internal codebases
Limited	Allowlisted domains only	Projects that need specific external APIs
Unrestricted	Full internet access	Open-source projects, tasks that require web APIs

Setup Script Always Has Internet

Internet access restrictions apply only to the agent phase. Setup scripts always have internet access for installing dependencies.

Domain Allowlisting

For limited access, configure allowed domains in environment settings:

• registry.npmjs.org — for npm package installs
• pypi.org — for pip installs
• api.stripe.com — for integration tests that call Stripe
• api.github.com — for GitHub API calls

Internet access risk

Unrestricted internet access means the agent can make HTTP requests to any domain. This creates prompt injection risk if the agent fetches content from untrusted sources. Use limited access with explicit domain allowlists whenever possible.

Best-of-N Strategies

When to Use Multiple Attempts

Cloud tasks support 1-4 parallel attempts. Use multiple attempts for:

• Critical fixes where the first approach might not work
• Complex migrations with multiple valid strategies
• Ambiguous tasks where you want to compare approaches

# Submit with 3 parallel attempts
codex cloud exec --env my-env --attempts 3 "Implement the caching layer for the user service"

Cost Consideration

Each attempt consumes credits independently. A 3-attempt task costs roughly 3x a single attempt. Reserve best-of-N for tasks where getting the right answer on the first try matters more than cost.

Reviewing Multiple Attempts

When multiple attempts complete, review each one in the Codex dashboard. Look at:

• Which approach the agent chose
• The test results for each attempt
• The size and complexity of the diff
• Whether the agent hit any errors during execution

Pick the best result and apply it, or use insights from multiple attempts to craft a more specific follow-up prompt.

Prompt: Cloud task with verification

codex cloud exec --env production-mirror --attempts 2 \
  "The /api/users endpoint returns stale data after profile updates.
   Reproduce the issue by writing a test that updates a profile and
   immediately reads it back. Find the caching bug, fix it, and verify
   the test passes. Also run the full user service test suite."

Two attempts increase the chance of finding the correct fix for a race condition.

CLI Workflows for Cloud Tasks

Submit and Monitor

# Submit a task
codex cloud exec --env my-env "Fix the failing integration tests"

# List recent tasks with status
codex cloud list --json | jq '.tasks[] | {title, status, url}'

# Apply a completed task's diff locally
codex apply TASK_ID

Interactive Picker

Run codex cloud with no arguments to open an interactive picker. Browse active and completed tasks, see their status, and apply diffs directly.

Press Ctrl + O in the picker to choose a different environment.

Scripted Batch Submission

#!/bin/bash
PACKAGES=("api" "web" "worker")
ENV_ID="my-env-id"

for pkg in "${PACKAGES[@]}"; do
  codex cloud exec --env "$ENV_ID" \
    "In the $pkg package, migrate from lodash to native JavaScript equivalents. Run tests." &
done

wait
echo "All cloud tasks submitted."

Environment Variables and Secrets

Variables vs. Secrets

• Environment variables: Available for the entire task duration (setup and agent phases). Visible in logs.
• Secrets: Encrypted at rest. Available only during setup scripts. Removed before the agent phase starts.

Use secrets for API keys, tokens, and credentials that the agent should not have direct access to. The setup script can use them to authenticate and download private packages, but the agent cannot echo or exfiltrate them.

Common Pattern

# Environment Variables (visible to agent)
NODE_ENV=test
DATABASE_URL=postgresql://localhost:5432/test

# Secrets (setup only)
NPM_TOKEN=your-private-registry-token
GITHUB_TOKEN=your-ghcr-token

When This Breaks

• Setup script times out: Move heavy installs to the setup script (not maintenance) so they are cached. Use --frozen-lockfile to avoid resolution.
• Agent cannot install packages: Internet access is off during the agent phase by default. Either install packages in the setup script or enable limited internet access.
• Cache keeps invalidating: Any change to setup scripts, maintenance scripts, or environment variables invalidates the cache. Batch your configuration changes.
• Task runs on wrong branch: Verify the branch selection when submitting. Cloud tasks check out the specified branch after cloning.
• Best-of-N attempts produce identical results: The task may be too deterministic. Add variability to the prompt: “Try different approaches for the caching strategy.”

What’s Next

• AGENTS.md Optimization — Ensure cloud tasks read the right project guidance
• Advanced Techniques — Combine cloud tasks with other surfaces
• Team Collaboration — Share cloud environments across your team