A Codex cloud environment is the reusable setup that every Codex Cloud task starts from: the GitHub repositories to check out, the dependencies and tools to install, the environment variables and secrets programs need, and the network access the task is allowed. You prepare it once, publish it, and each new task gets an isolated copy.
This guide goes deeper than the Codex Cloud overview on the configuration itself: scripts, packages, secrets, internet access and caching. It follows OpenAI's Cloud environments and Codex Cloud (Legacy) docs, read on 26 October 2026.
Which kind of Codex cloud environment are you using?
There are two experiences today, and they configure things differently:
| Current Codex Cloud | Codex Cloud (Legacy) | |
|---|---|---|
| Used by | Tasks on the web, desktop app and mobile | Code Review and the GitHub and Linear integrations |
| Setup | Codex prepares and tests it in a conversation, then you publish | You configure fields in Codex settings |
| Scripts | Install script and start skill | Setup script and optional maintenance script |
| Credentials | Environment variables and network secrets | Environment variables and secrets |
| Reuse | Published filesystem, per-task saved state | Container cache for up to 12 hours |
OpenAI says it plans to deprecate the Legacy experience. If you trigger tasks with @codex on GitHub pull requests, though, your environment still runs there today, so both sets of settings matter.
How do setup scripts work?
Current experience. You don't have to write anything. The docs say Codex "identifies runtimes, package versions, tools, and services from your repositories," and you refine the setup in conversation, for example asking for a specific Node.js version or a database service. Codex then records the tested setup in two fields:
- Install script: commands to install dependencies and prepare development assets.
- Start skill: instructions to start services and check they are ready.
When setup fails, check the setup conversation for the failing command and ask Codex to diagnose it. If initial setup fails, you can also select Try again. If the fix needs a source file, manifest or lockfile change, make it in a coding task first, then return to setup.
Legacy experience. For projects using npm, yarn, pnpm, pip, pipenv or poetry, Codex can install dependencies automatically. For anything more involved, you write a setup script. The docs' example:
# Install type checker
pip install pyright
# Install dependencies
poetry install --with test
pnpm install
One detail trips people up. In the docs' words, "Setup scripts run in a separate Bash session from the agent, so commands like export do not persist into the agent phase." To keep a variable, add it to ~/.bashrc or set it in the environment settings:
# Example: persist a value for the agent phase (legacy setup script)
echo 'export APP_MODE=test' >> ~/.bashrc
The optional maintenance script runs when a cached container is resumed. Use it to update dependencies when the cache was built on an older commit.
Which packages and runtimes are preinstalled?
In the Legacy experience, the agent runs in a default image called universal, which "comes pre-installed with common languages, packages, and tools." In the Legacy settings, Set package versions pins Python, Node.js and other runtimes. In the current experience you ask for versions during setup.
OpenAI publishes a reference image at openai/codex-universal. Its README says the image "is not an identical environment but should help for debugging and development." It installs language runtimes chosen by CODEX_ENV_* variables (Python, Node.js, Rust, Go, Swift, Ruby, PHP and Java), plus tools such as bun, bazel, erlang and elixir. Python comes with poetry, uv, ruff, mypy and pyright; Node.js comes with corepack, yarn and pnpm.
To approximate a cloud setup on your own machine, adapted from the README:
docker run --rm -it \
-e CODEX_ENV_PYTHON_VERSION=3.12 \
-e CODEX_ENV_NODE_VERSION=20 \
-v $(pwd):/workspace/$(basename $(pwd)) -w /workspace/$(basename $(pwd)) \
ghcr.io/openai/codex-universal:latest
The image is built for linux/amd64 and linux/arm64, but the README notes "we only run the linux/amd64 version," so add --platform linux/amd64 on Apple silicon if you want to match.
How do environment variables and secrets work?
Current experience. Select Manage beside Environment variables or Network secrets and pick a type:
| Type | Use it for | How programs see it |
|---|---|---|
| Environment variable | A value a program must read, such as APP_MODE=development |
The raw value |
| Network secret | A credential sent to an HTTPS service, such as a private registry token | A placeholder; the proxy substitutes the real value for allowed domains |
A network secret has a Key, a Value and Allowed domains. Substitution "works for HTTPS on port 443, during setup and tasks," and the raw credential never lands in a local process or file. If a program truly needs to read the raw value, store it as an environment variable instead. Saving an environment-owned network secret also adds its domains to restricted internet access.
For shared environments, each person can supply their own values from Settings > Codex Cloud > Personal vault, scoped to all environments or selected ones. "Only requested values reach a task," and a value for a specific environment beats a general default.
Legacy experience. Environment variables last for the whole task. Secrets are stored "with an additional layer of encryption," and the docs say: "They are only available to setup scripts. For security reasons, secrets are removed before the agent phase starts." So a legacy secret can authenticate npm install during setup, but the agent cannot call that API later.
How does internet access work?
Current experience. Turn on Allow Codex to access internet, then choose:
- Package managers: a preset covering registries such as
registry.npmjs.org,pypi.org,crates.io,proxy.golang.org, Maven and Gradle hosts, Ubuntu and Debian repositories, and GitHub source, release and LFS hosts. - Custom domains only: just the hosts you add under Additional allowed domains.
- All (unrestricted): for workflows that need broad access.
For a registered root domain Codex also allows the www hostname, but other subdomains need their own entries. "Allowing a destination doesn't supply credentials or grant permissions in that service." If a service filters by source IP, OpenAI publishes an agent egress IP feed and advises checking it daily.
Legacy experience. "Setup scripts still run with internet access so you can install dependencies," while agent access is off by default. The internet access docs offer a domain allowlist (None, Common dependencies or All) and an option to restrict requests to GET, HEAD and OPTIONS, blocking POST, PUT, PATCH and DELETE. All traffic passes through an HTTP/HTTPS proxy.
The same page lists the risks of agent internet access: prompt injection from untrusted content, code or secret exfiltration, malware or vulnerable dependencies, and license-restricted content. Allow only what the task needs.
How does caching and saved state work?
Current experience. Three rules cover it:
- New task: starts from the published environment's prepared filesystem.
- Existing task: keeps its own files, "including uncommitted changes and installed tools."
- Repository refresh: runs in the background, "preserving dependency caches without rerunning installation or startup commands."
To change the shared setup, open the environment's … menu, select Edit, let Codex test the change and select Republish. Existing tasks keep their state. A task's saved VM state is recoverable for up to seven days after you last start a turn or resume it, but "Saved state doesn't replace source control."
Legacy experience. "Codex caches container state for up to 12 hours." When caching, it clones the repo, checks out the default branch and runs the setup script. When resuming, it checks out the task's branch and runs the maintenance script. The cache is invalidated automatically when you change the setup script, maintenance script, environment variables or secrets; otherwise select Reset cache. On Business and Enterprise, caches are shared across everyone with access, so a reset affects the whole workspace.
How do you reach private services?
The current experience adds two options under Advanced:
- VPN: Tailscale is the supported provider today. Create an auth key with both Reusable and Ephemeral enabled, and allow the destinations in both Tailscale's access rules and the environment's internet settings. Split DNS and MagicDNS work; hostnames must resolve to IPv4.
- OIDC: tasks obtain short-lived credentials for AWS, Google Cloud or Azure. Support varies by service, so check OpenAI's compatibility tables. For example, AWS CLI, S3 and ECR are supported, while Azure Blob Storage is not yet.
What should you put in the environment and what in the repo?
- Commands go in AGENTS.md. Build, test and lint commands there tell every task how to check its work.
- Skills go in the repo. The docs say repository skills are available in cloud tasks, but "Personal skills from your local computer aren't synced." See Codex skills.
- Republish after dependency changes. New tasks start from the published snapshot, not your latest lockfile.
- Prefer network secrets. A program that only sends a token to an API doesn't need the raw value.
If you are weighing remote agents more broadly, Codex vs Amp compares cloud environments with Amp's orbs, and Codex approvals and sandbox covers the local side.
Keep your skills where cloud tasks can find them
Cloud tasks only see skills committed to the repository, so keeping skills in Git matters. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own and installs every skill into Claude Code or Codex with one npx skills add command. The free SKILL.md generator turns a prompt into a skill folder you can commit to .agents/skills/.