codex-environments

Codex Environments

Use this skill to manage repo-local Codex app environments: usually .codex/environments/environment.toml plus optional project scripts called by actions.

For long-running action patterns, port cleanup, detailed editing rules, verification depth, and common failure modes, read ../../references/environment-actions.md.

Decide Whether To Create Or Edit

Create or edit a Codex environment when the user wants a repeatable Codex app action, such as Run, Test, Preview, Open Simulator, Start Dev Server, Launch Browser, or a stable local workflow behind a Codex Run button.

Prefer a repo-local environment when:

• the command must run from a specific project root;
• the workflow needs stable env vars, ports, simulators, devices, URLs, or log paths;
• the user is repeatedly pasting the same long command;
• Codex Run should start an app or local service without manual shell assembly.

Do not create an environment for a one-off command, destructive operation, secret setup, or workflow that still needs product decisions. Give the command directly unless repeatability is the point.

If the environment file already exists, update it instead of creating a parallel file. Preserve unrelated actions and setup script content.

File Shape

Use this structure:

version = 1
name = "project-name"

[setup]
script = ""

[[actions]]
name = "Run"
icon = "run"
command = '''
cd /absolute/project/root
./scripts/run-local.sh
'''

Common optional action fields may appear in existing files, such as platform = "darwin". Preserve them when still correct.

Use absolute project paths inside actions unless the action is guaranteed to be launched from the repo root. Absolute paths make Codex app actions less sensitive to caller cwd. Do not commit personal paths into shared templates or plugin source.

Command Design

Keep environment.toml small. If an action needs more than a few lines, create a repo-local script such as scripts/run-dev.sh and call it from the action.

Use scripts for:

• multi-step server startup;
• port cleanup and readiness polling;
• simulator/device launch logic;
• log redirection;
• fragile shell quoting;
• commands users might otherwise paste incorrectly.

In scripts:

• use #!/usr/bin/env bash and set -euo pipefail;
• parameterize safe knobs with env vars, for example PORT="${APP_PORT:-3000}";
• keep secrets out of files and logs;
• write long-running service logs to a known local path such as /tmp/project-name.log;
• check prerequisites before doing work and print actionable errors.

Avoid putting secrets, tokens, cookies, auth headers, API keys, passwords, or signing material into environment.toml. Reference ignored local files or existing env vars instead.

Editing Rules

Before editing:

• inspect the existing environment file;
• inspect any script the action currently calls;
• identify whether the file says it is autogenerated.

If a file says THIS IS AUTOGENERATED, still follow the user's direct request, but keep the patch minimal and be ready for future regeneration. Prefer changing the script called by the action when possible.

Use apply_patch for manual edits. Preserve unrelated user changes. Add scripts under the project, usually scripts/, and keep environment.toml as the small launcher surface.

Verification

After edits, validate at the right depth:

• TOML syntax: parse with an available TOML parser if one exists, or inspect carefully when no parser is available.
• Script syntax: run bash -n scripts/name.sh.
• Executability: run chmod +x scripts/name.sh for direct scripts.
• Smoke: run the action command or script long enough to prove startup, readiness, and expected UI/browser/simulator behavior.
• Cleanup: stop any process started during verification unless the user asked to leave it running.

For long-running scripts, use a bounded smoke run from Codex, verify readiness in another check, then terminate the process you started. Use the reference for foreground log streaming and port cleanup patterns.

Report exact commands that passed and any commands not run.

Common Failure Modes

• suspended (tty output): background process wrote to TTY.
• event not found in zsh: pasted command contains !.
• Dev client cannot load from 127.0.0.1: server exited after launch.
• Port says it is running another app: clear only the intended listener.
• Action works in shell but not Codex app: replace relative paths and prompts.