/codex-sandbox

name: codex-sandbox
description: >
  USE WHEN setting up Codex CLI in a project, tightening sandbox for
  prod/CI, or when user asks about Codex permissions. Interactive
  helper for per-project `.codex/config.toml`: `dev` / `prod` /
  `custom` profiles, idempotent via markers, preserves unmanaged
  config below the block. Codex-only artifact.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(ls:*)
  - Bash(test:*)
  - Bash(git rev-parse:*)
argument-hint: "[target-dir] [--profile dev|prod|custom] [--noninteractive]"

/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. |

> There is deliberately no `staging` profile: Codex config exposes no > audit-log field, so a "staging" tier would differ from `dev` / `prod` in > name only. For CI, use `dev` (keeps approvals) or `prod` (read-only > sandbox); pipe Codex's 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 Code