Codex Cloud Environments skill for Codex

A cloud environment is ready when a new task starts from a published, tested setup in which the project’s own test command passes, every needed host is reachable and no other, credentials reach only the services that need them, and the repository’s AGENTS.md tells the agent which commands to run.

Two kinds of environment

	Current Codex Cloud	Codex Cloud (Legacy)
Used by	Tasks started on web, mobile, desktop app (Work in > Cloud), codex cloud, Slack/Teams delegation	Code Review, @codex tasks from GitHub PRs, Linear integration
Setup	Codex inspects repos, installs and tests in a setup conversation; records an Install script and a Start skill	You write a setup script (and optional maintenance script) on the universal image
Lifecycle	Save, then Publish; edits need Republish; new tasks use the published filesystem	Container state cached up to 12 hours; changing scripts, variables or secrets invalidates the cache
Credentials	Environment variables (raw value) or network secrets (placeholder substituted by the proxy for allowed HTTPS domains); Personal vault for per-user values	Environment variables (whole task) and secrets (setup script only, removed before the agent runs)
Network	Allow internet: Package managers preset, Custom domains only, or All (unrestricted); VPN and OIDC under Advanced	Setup has internet; agent phase off by default, or on with a domain allowlist and optional GET/HEAD/OPTIONS-only restriction

Configure current environments under Settings > Codex Cloud > Environments; legacy ones at chatgpt.com/codex/settings/environments.

Workflow

- [ ] 1. Make the repo self-describing (AGENTS.md commands, lockfiles, version files)
- [ ] 2. Create the environment and let setup run the real test command
- [ ] 3. Add variables, network secrets and allowed domains, least first
- [ ] 4. Publish; start a fresh task that runs the tests
- [ ] 5. Record the environment's purpose and owner; share deliberately

1. Prepare the repository

Setup quality follows what the repo declares. Before creating the environment:

• AGENTS.md lists install, test and lint commands that run without manual steps.
• Runtime versions are pinned (.nvmrc, .python-version, .tool-versions, packageManager in package.json, rust-toolchain.toml).
• Lockfiles are committed. Services the tests need have a documented start command.
• Repo skills in .agents/skills/ are available to cloud tasks; personal skills from your machine are not.

2. Create and test (current Cloud)

Choose Work in > Cloud > Select environment > Create environment, pick the GitHub repositories, select Get started, and answer Codex’s questions. Ask for specifics:

Use Node 22 and pnpm 9 from packageManager. Run `pnpm install --frozen-lockfile` in the
install script. Start Postgres 16 and Redis in the start skill and wait until both
accept connections. Prove the setup by running `pnpm test --filter=api`.

If a fix needs source, manifest or lockfile changes, make them in a normal coding task, merge, then return to setup. Review the setup report, configuration and files, then Publish. After “Environment published”, start a new task.

3. Access, least first

Need	Configure
A program reads a value directly (APP_MODE, non-secret config)	Environment variable
A token sent to a specific HTTPS service (private registry, API)	Network secret with Allowed domains; programs only see a placeholder
Each user must supply their own credential	Request it as a personal value; users add it in Personal vault
Package registries only	Allow internet > Package managers preset
Also a few specific hosts	Add them under Additional allowed domains (exact hostnames; subdomains need their own entries)
Internal services	Advanced > VPN (Tailscale auth key: Reusable and Ephemeral), plus allow the hosts
AWS, GCP, Azure resources	Advanced > OIDC connection with a narrowly scoped role; test one allowed and one denied operation

Network secrets work for HTTPS on port 443 only, and they add their destinations to the allowed list. Use a key name different from any direct variable. If a program must read the raw secret, it has to be an environment variable, which every command in the task can read: prefer network secrets.

4. Publish and verify

Save, Publish (or Republish after edits), then start a new task: existing tasks keep their own saved state and do not pick up environment changes.

Verify the environment: print tool versions, run the full test suite, and try to reach
https://example.com (should be blocked). Report results; do not change files.

From a terminal:

codex cloud                                   # interactive picker of tasks and environments
codex cloud exec --env <ENV_ID> "Run the test suite and report failures"
codex cloud exec --env <ENV_ID> --attempts 3 --branch feat/x "Implement step 2 of docs/plans/x.md"
codex cloud list --json --env <ENV_ID>       # tasks with id, url, status
codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>
codex cloud apply <TASK_ID> --attempt 2      # or: codex apply <TASK_ID>

apply runs git apply locally and exits non-zero on conflicts; apply onto a clean tree.

5. Share and maintain

Under Privacy > Who can use, choose the workspace only for environments meant for everyone; sharing gives others the setup and environment-owned credentials’ effects, not your personal values or tasks. Review prepared files and credentials first. Record owner and purpose in the environment description or a team doc. Task VM state is recoverable for up to seven days after the last turn.

Legacy environments (Code Review, GitHub and Linear tasks)

• Default image universal (reference: the openai/codex-universal repo, which can be pulled and run locally to reproduce). Pin runtime versions with Set package versions.
• Automatic setup handles npm, yarn, pnpm, pip, pipenv and poetry projects. For anything else, write a setup script:

  pnpm install --frozen-lockfile
  pip install -r requirements-dev.txt
  echo 'export DATABASE_URL=postgres://localhost/test' >> ~/.bashrc   # export alone does not persist

• The setup script runs in a separate Bash session from the agent; persist variables in ~/.bashrc or environment settings.
• Maintenance script: runs when a cached container resumes on a newer commit; use it for pnpm install style refreshes.
• Secrets exist only during setup. Fetch private packages in setup, not at agent time.
• Agent internet is off by default. If enabled, start from no domains or Common dependencies, add only what fails, and restrict methods to GET, HEAD, OPTIONS when possible.
• Use Reset cache after incompatible repo changes. In Business and Enterprise workspaces caches are shared, so a reset affects everyone using the environment.

Gotchas

• Enabling broad internet access exposes tasks to prompt injection from fetched content (issues, READMEs, web pages) and to exfiltration. Allow the narrowest domain set.
• Allowing a domain does not authenticate to it; check the client’s configured URL and credentials separately. Exact hostnames matter: a registry often redirects downloads to a second host.
• Unpublished environments cannot be selected for tasks; look for the Unpublished badge.
• VPN-reachable services must also be allowed in the environment’s internet settings, and curl tests should go through the environment proxy (do not pass --noproxy).
• Current limitations: no GitLab or self-hosted GitHub Enterprise Server, no browser or computer use inside cloud environments.
• Saved cloud state is not source control. Commit or download what matters.

Output contract

**Environment:** api-monorepo (published 2026-10-28, owner @dana, shared: workspace)
**Setup:** Node 22, pnpm 9, Postgres 16 via start skill; `pnpm test --filter=api` passes in a new task
**Access:** Package managers + npm.pkg.github.com; network secret NPM_TOKEN (npm.pkg.github.com only)
**Blocked check:** example.com unreachable as intended