Cloud Environments & Internet Access

When you delegate a task to Codex cloud, it does not run on your laptop. It spins up a fresh cloud sandbox container — its own isolated machine — does the work there, and hands you back a diff and (optionally) a pull request. A cloud environment is the saved recipe that tells Codex how to build that container every time.

Think of it like a Dockerfile plus a network policy that you configure once and reuse for every task on a repo. Get the recipe right and your tasks are reproducible and safe: the same dependencies install, the same tools are present, and the agent can only reach the network you allow. Get it wrong and tasks fail in confusing ways — a missing compiler, a test suite that can't reach its database, a setup that worked once and then broke.

Environments are configured in Codex settings → Environments, and they are per repository: you set one up for a repo before delegating cloud tasks to it. Here is the lifecycle Codex runs for every task:

1. Create a container and check out your repo at the chosen branch/commit.
2. Run your setup script (and an optional maintenance script when resuming a cached container).
3. Apply internet-access settings — note that setup scripts have internet on by default.
4. Run the agent loop — Codex edits files and runs terminal commands to validate, repeating until done.
5. Show results and a file-change diff you can review and turn into a PR.

The rest of this lesson walks each layer of that recipe: the base image, dependencies, scripts, secrets, caching, and the network policy.

Every environment starts from a base image — the pre-built container with an operating system, languages, and tooling already installed. Codex's default is the universal image (published as openai/codex-universal on GitHub), which ships a broad set of pre-installed languages, packages, and developer tools so most repos work with zero extra configuration. If your project pins a specific runtime, you can pin specific versions of Python, Node.js, and so on rather than taking the image defaults.

On top of the image, Codex tries to install your project's dependencies automatically. It detects and runs the common package managers it finds:

If a lockfile or manifest for one of these is present, Codex installs from it without you writing any script. You only need a custom Bash setup script when auto-install isn't enough — for example, native build dependencies, a private registry, a database to seed, or a monorepo with an unusual layout (covered next).

Because exact image contents and the pre-installed toolchain versions shift over time, treat them as volatile and check the live reference rather than memorizing a list.

Two script hooks let you customize the container beyond auto-install:

• Setup script — a custom Bash script that runs when the container is first built. Use it for anything auto-install can't do: installing system libraries, seeding a test database, building native modules, configuring a private registry.
• Maintenance script (optional) — runs when Codex resumes a cached container (see caching below) instead of rebuilding from scratch. Use it for fast, incremental refresh steps — e.g. pulling the latest branch state or re-seeding ephemeral data — so a resumed container is up to date without paying the full setup cost again.

Now the gotcha that bites almost everyone. The setup script runs in a separate Bash session from the agent. That means a variable you set with export in the setup script does not persist into the agent phase — the agent runs in a different shell and never sees it.

# setup script — this DOES NOT reach the agent phase:
export MY_FLAG=1            # ❌ gone once setup's shell exits

# Instead, persist it so the agent's shell picks it up:
echo 'export MY_FLAG=1' >> ~/.bashrc   # ✅ survives into the agent session

For non-secret configuration, the cleaner path is to set environment variables in the environment settings themselves — those are available for the full task, both setup and agent phases, with no ~/.bashrc trick required.

This is the single most important safety rule in the whole lesson, so internalize it: Codex distinguishes plain environment variables from secrets, and they have different lifetimes.

A secret gets extra encryption and is exposed only to your setup script — it is removed before the agent phase begins. So a secret can authenticate to a private package registry or fetch a private dependency during setup, but by the time the model is reading your code and running commands, that credential is gone.

Why design it this way? Because the agent phase is where untrusted content enters — code, files, and (if you enable it) the web. A model influenced by a prompt-injection payload could try to read and exfiltrate any secret it can see. Stripping secrets before the agent runs removes that prize from the table entirely. Plain (non-secret) environment variables, by contrast, are available for the full task — which is exactly why you must never put a credential in one.

The practical workflow: do all credentialed work in the setup script (install the private package, clone the private repo, write a non-secret derived artifact the agent can use), and let the agent phase run with no live credentials present.

The second rule people get wrong: during the agent phase, internet access is OFF by default. Setup scripts keep internet on (so dependency installs work), but once the agent starts editing and validating, it cannot reach the network unless you explicitly turn it on. This is a deliberate safety default — an offline agent can't be steered by malicious web content into exfiltrating data.

Internet access is configured per environment, and when enabled all outbound traffic routes through an HTTP/HTTPS proxy so policy can be enforced. The setting has three states:

• Off — block all outbound traffic in the agent phase (the default).
• On (unrestricted) — allow everything (use sparingly).
• On (restricted) — allow, but constrained by two independent controls below.

When restricted, you tighten access along two axes:

The HTTP-method restriction is a clever, underused control: limiting the agent to read-style methods (GET/HEAD/OPTIONS) lets it fetch documentation or packages while preventing it from writing data to an external service — a strong brake on exfiltration even when a domain is allowed.

The documented risks of opening internet access are concrete: prompt injection from untrusted web content, credential exfiltration, malware, and license-compliance problems. The standing recommendation is to restrict to trusted domains, prefer the read-only method set when you can, and review the agent's output.

The allowlist preset size (~80+ domains) and exact membership are volatile — verify the current list against the live internet-access docs.

Building a container from scratch — image + dependency install + setup script — is slow. To keep delegated tasks fast, Codex caches container state for up to 12 hours. When a new task lands within that window, Codex can resume the cached container (running your optional maintenance script to refresh it) instead of rebuilding everything.

The cache is not magic; it invalidates when the recipe meaningfully changes. The cache is dropped when you change any of:

• the setup script or the maintenance script,
• the environment variables, or
• the secrets.

You can also manually reset the cache from the environment page when you want a guaranteed-clean rebuild (for example, after you suspect stale state). The 12-hour TTL is volatile — confirm the current value in the environments docs.

Finally, zoom back out to placement. Environments are per repository, configured before you delegate. That ordering matters: a cloud task with no environment set up (or a broken one) is exactly how you get the 'missing dependency / can't reach the network' failures from the start of this lesson. Configure the environment first, validate it once with a small task, and then delegate real work against a recipe you trust.