codex-sandbox

/codex-sandbox

What it does

Codex CLI runs each agent inside a sandbox with a configurable permission model (filesystem, network, dangerous commands). The defaults are conservative; per-project overrides live in .codex/config.toml at the project root.

This skill asks 3–5 questions, recommends a profile, and writes the file. Re-running on an already-configured project detects the managed block (marker comments) and offers update-in-place.

What lives in .codex/config.toml

The skill writes only the policy-relevant sections (and leaves room for the user to add unrelated config below):

# <!-- claude-leverage:codex-sandbox START -->
# Managed by /codex-sandbox. Edit between markers and re-run the skill
# to update; do not delete the markers.

[project_doc]
max_bytes = 32768                # explicit; matches Codex default

[sandbox]
mode = "<workspace-write | read-only | full>"

[approval]
mode = "<on-request | on-failure | never>"
# <!-- claude-leverage:codex-sandbox END -->

The pre-baked profiles

Profile	Sandbox	Approval	Use for
dev	workspace-write	on-request	Local development. Agent can write inside the project but asks before risky actions (network, package install, shell commands outside cwd).
prod	read-only	never	Production / CI runs. Agent can only read; any write requires running outside the sandbox.
custom	(asks)	(asks)	Anything else; skill walks you through each field.

Earlier drafts proposed a staging profile with "audit logging" — that claim was incorrect (Codex config has no audit-log field). For CI / staging behavior, use dev if you want approvals or prod if you want the safer read-only sandbox, and pipe Codex's own stderr to your log aggregator if you need an audit trail.

Field names below are what Codex currently documents. If the spec evolves, this skill will need a refresh — /stack-check does not yet verify Codex spec freshness (v1.1 candidate).

Workflow

1. Resolve target dir. Default cwd. If $ARGUMENTS has a path, use that. Verify it's a git repo or ask "this isn't a git repo; proceed anyway?".

2. Detect existing config. If .codex/config.toml exists:

   • With managed markers: parse current sandbox + approval modes, show them to the user, offer to keep, update, or pick a new profile.
   • Without managed markers: ask "an unmanaged .codex/config.toml exists; prepend a managed block above it, replace, or skip?".

3. Choose profile (unless --profile <name>):

   Pick a profile:
     1. dev      — workspace-write, on-request approvals (recommended for local)
     2. prod     — read-only sandbox, no approvals (CI / production)
     3. custom   — answer each question individually
   

   Unless --noninteractive, wait for a choice. With --noninteractive and no --profile, default to dev.

4. For custom, walk the user through:

   • Sandbox mode: read-only / workspace-write / full + explain each.
   • Approval mode: never / on-request / on-failure + explain each.
   • project_doc.max_bytes: keep default 32768 or set higher (warns this exceeds Codex's silent-drop cap if user picks higher).
   • TODO: additional Codex sandbox fields like writable-roots / network-allowlist are not yet documented stably across Codex versions; this skill emits only the mode fields for now. Verify against the live spec before adding more.

5. Write the managed block.

   • If no .codex/config.toml exists: create file with managed block as the only content.
   • If file exists with managed block: replace the block in place via Edit (markers stay byte-identical).
   • If file exists without managed block: prepend managed block above existing content.

6. Report. Print the resolved config + a one-line summary. Suggest the user runs codex --version or starts a fresh Codex session to pick up the change.

Hard rules

• Never delete unmanaged config below the managed block. The block contract is "I own what's between my markers; everything else is yours."
• Never lower the sandbox below read-only without explicit acknowledgement. If the user picks full, surface a one-line reminder: "full sandbox lets the agent do anything in the filesystem; only use for trusted scripts."
• Never invent fields outside the spec. If a future Codex version adds new fields, this skill doesn't auto-include them; re-run after a plugin update.
• Refuse on non-git dirs unless explicitly allowed. Same as /init-repo — protect against random-dir foot-guns.

Tunables

• --profile dev|prod|custom — skip the picker. Default is dev.
• --noninteractive — confirm nothing, use profile (default dev).
• --dry-run — print what would be written, write nothing.

When to run

• First time setting up Codex in a project.
• After a Codex CLI version bump that changes default sandbox behavior (rare, but documented in changelogs).
• When tightening a project's sandbox for production / CI runs.

What this skill does NOT do

• Configure ~/.codex/config.toml (global). Global Codex config is a user-level decision; this skill only writes the per-project .codex/config.toml. For global, edit by hand.
• Touch ~/.codex/hooks.json or ~/.codex/AGENTS.md. Those are owned by scripts/install-codex.sh (and its uninstall path).
• Install Codex CLI. Codex must already be installed (npm i -g @openai/codex); this skill just configures it.

Notes for Claude Code users

If you invoke /codex-sandbox from a Claude Code session, the skill will note up front:

This skill writes .codex/config.toml, which only affects how Codex CLI behaves in this project. Claude Code does not read Codex config; your Claude Code experience is unchanged.

The skill still runs (it's a file-writer; the file just happens to be Codex-relevant). This is useful when setting up a fresh project in Claude Code that you also plan to work on from Codex.