Codex CLI Tutorial: Setup, Sandbox, and AGENTS.md

Step 0 — Install and authenticate

Three install paths. On Windows there is a native build — no WSL required (shipped May 2026); npm works everywhere if you already run Node 22+:

# macOS / Linux (standalone installer)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Windows (PowerShell) — native
npm install -g @openai/codex
# Homebrew alternative
brew install codex
codex --version

Two gotchas beginners hit in minute one. First, the package is @openai/codex — the unscoped codex on npm is an unrelated 2012 project. Second, on Windows the native binary needs the VC++ runtime (winget install Microsoft.VCRedist.2015+.x64); without it, Codex exits silently with no error. Verify with codex --version, then codex doctor — it diagnoses install, config, auth, and runtime health in one shot and is the first thing to run whenever anything is wrong.

Then codex from any project directory. Sign in with your ChatGPT account — Codex is included in every plan (Free trial, Plus $20/mo, Pro 5x $100/mo, Pro 20x $200/mo), or point it at an API key for usage-based billing with no plan windows. A Plus seat is enough for daily work; the allowance is a rolling 5-hour window (OpenAI publishes per-model ranges, roughly 10–100 messages on GPT-5.6 Sol for Plus), with weekly caps on top for heavy use.

Step 1 — First session: trust and the agent loop

Start in a real project. Codex boots conservative until you trust the directory — it can read, but every edit asks first:

cd my-project
codex
> Explain the architecture of this project. Do not modify anything.

Trust the repo through the onboarding prompt or /permissions → "Trust this directory", and the default preset upgrades to Agent: writes inside the workspace flow without prompts, and Codex only interrupts you when an action must leave the sandbox. The loop is the same mental model as every coding agent — goal, tool, result, repeat — with one difference: every command runs inside an OS-level sandbox (Seatbelt on macOS, Landlock+seccomp on Linux, an AppContainer profile on Windows), not inside a container and not on the honor system.

Input basics: @src/auth.ts attaches a file, /mention <path> does the same from the palette, and a bare ? lists shortcuts. Esc interrupts mid-turn; Ctrl+G opens your prompt in an external editor; double-Esc walks back through your message history. /status is your ground truth — model, approval policy, writable roots, and context capacity — check it whenever behavior confuses you instead of guessing which config layer won.

Step 2 — The commands that matter

Codex ships 40+ slash commands and a dozen subcommands; five subcommands and six slash commands cover about 90% of real sessions. Anything older guides told you about --full-auto is stale — it was removed. The flags that matter: -s for sandbox, -a for approvals, -m for model, -p for a profile, -c key=value to override any config key for one run.

In-session extras worth knowing: /mcp lists connected servers, /skills browses installed skills (invoke one as $skill-name), /agent switches active subagent threads, /memories toggles memory injection, and /import pulls your setup from Claude Code — instructions, settings.json, skills, slash commands, and the last 30 days of chats land as native Codex equivalents. On Windows there are two more: /setup-default-sandbox and /sandbox-add-read-dir.

Step 3 — Sandbox and approvals: the control surface

This is the part most tutorials wave past and the part that decides whether you trust the agent. Two independent dials: sandbox_mode controls what Codex can technically do; approval_policy controls when it must ask first:

The job-to-flags mapping that keeps you safe: reviewing a diff or triaging an issue is -s read-only -a never; a scripted refactor is -s workspace-write -a never after committing (a git checkpoint is the real rollback); a reproducible CI run adds --ignore-user-config --ephemeral so the run is hermetic. Old --full-auto spelled out the same pair — the shorthand was removed because it loosened both dials at once while hiding that fact.

The pattern that works in practice: read-only plan → workspace-write execute → /review. Plan the approach without write access, switch modes and let it work, then run the review and your own test suite. Skip the plan phase on typo-level tasks — that round trip is pure overhead there.

Step 4 — AGENTS.md: the memory that makes it good

Codex reads AGENTS.md before doing any work, and it is the highest-leverage configuration: a short, specific file changes behavior more than any flag. Run /init in your repo and it scaffolds a starting file. The shape that earns its tokens:

# Project: billing-service
## Stack
- Bun + Hono on PostgreSQL (Drizzle ORM). Never suggest npm.
## Commands
- bun dev / bun test / bun db:migrate
## Conventions
- TypeScript strict. Tests colocated as *.test.ts.
## Don't
- Don't touch src/legacy/ — frozen.
- Don't add dependencies without asking.

Discovery walks from the git root down to your working directory, concatenating one file per level — closer files override broader guidance because they appear later in the combined prompt. AGENTS.override.md replaces everything at its level. The global file (~/.codex/AGENTS.md) holds your personal defaults: review style, verbosity, how to run tests. The combined chain caps at project_doc_max_bytes (32 KiB by default — raise it or split across nested directories when you hit it). Verify what loaded: codex --ask-for-approval never "Summarize the current instructions."

The cross-tool payoff is why this file matters more in Codex than anywhere else: AGENTS.md is a Linux-Foundation-governed standard that Codex, Cursor, Copilot, Gemini CLI, Devin, Aider, Zed, and 25+ tools read natively — the notable exception is Claude Code, which auto-loads CLAUDE.md instead. The one-line bridge: a CLAUDE.md containing only @AGENTS.md plus your Claude-specific overrides. One source of truth, every agent. Our AGENTS.md template covers the five sections that survive contact with real repos.

Step 5 — Skills, MCP, and config.toml

Anything you paste into chat more than twice wants to be a skill. Codex reads the same SKILL.md format as other agents: repo skills in .agents/skills/<name>/SKILL.md (checked in, shared via git), personal skills in ~/.agents/skills/, machine defaults in /etc/codex/skills/. Invoke explicitly with $skill-name or let Codex auto-trigger from the description match:

---
name: deploy
description: Ship the current branch to staging with checks.
---
Run the pre-deploy checklist: bun test, bun lint, then
deploy to staging with bun run deploy:staging. Report
each gate's result before moving to the next.

Long reference material belongs in files beside the SKILL.md — the entry point stays short enough to review, and detail loads only when used. MCP servers extend tools instead of commands: codex mcp add wires them into ~/.codex/config.toml, /mcp lists what is live, and if a skill depends on one, declare it in agents/openai.yaml so Codex installs the dependency automatically. Legacy custom prompts are deprecated in favor of skills.

~/.codex/config.toml is the last layer: model choice (model = "gpt-5.6", reasoning effort), sandbox and approval defaults, profiles as separate <name>.config.toml files, MCP servers, and project trust knobs. Precedence, top to bottom: CLI flags, then trusted project config (.codex/config.toml), then user config, then built-ins — /status shows the effective result, so never guess. Run codex doctor before debugging anything by hand.

Step 6 — codex exec: the CI surface

The interactive TUI is half the product. codex exec is the other half — a scriptable, pipeable agent runtime:

# one shot: progress to stderr, final answer to stdout
codex exec "summarise what changed in the last 10 commits"

# safe in CI: cannot write, cannot ask
codex exec -s read-only -a never "review the diff on this branch"

# read the prompt from stdin
git diff --cached | codex exec -

# machine-readable events + validated final output
codex exec --json -o /tmp/answer.md "audit this package for unused exports"

Three exec features turn it from a one-shot pager into a pipeline runtime: --output-schema validates the final response against a JSON Schema, so a script can branch on the result instead of parsing prose; --json streams the whole event log as JSONL; and codex exec resume --last chains stages onto the same session context (inventory → plan → execute), each with its own schema.

The same discipline applies as with any agent in CI: run hermetic (--ignore-user-config --ephemeral), keep the sandbox at the smallest permission that works, and commit before any workspace-write run so the diff is the reviewable artifact.

Step 7 — Verify (the step beginners skip)

The agent says done. Your job is not done. Three closes, every time:

This is not ceremony — it is the loop that separates developers who get real leverage from agents from those who ship subtle bugs.

Run Codex beside your other agents

Codex CLI is a terminal agent; a harness decides where it runs and what it can touch. VibeFuse is the first ever free widget-based AI harness: Codex, Claude Code, Gemini, Cursor Agent, and Qwen as live widgets on one Windows canvas — sessions named and resumable, parallel agents on separate worktrees, MCP tools attached, local Whisper voice control, all processing local/offline. The harness is $0; you pay only the OpenAI plan you already use.

Skills you write for Codex are portable: VibeFuse reads the same SKILL.md format, and the open-source marketplace lets you sell your skills, widgets, and styling packs with 80% payouts to creators via Stripe Connect. Works in any app you already use.

Explore VibeFuse & harness guides

• Harness Guide
• Free Coding Tools
• AI Coding Agent Desktop
• Free Voice Transcription
• Free Text to Speech
• VibeFuse Product
• Widget Marketplace
• Download Free
• VibeFuse Docs
• Shareable AI Widgets
• Shareable AI Skills
• MCP Tools
• AI Agent Harness
• Harness Engineering
• HyperFrames Video
• Skill Seekers
• Sell AI Skills
• AI Skills Marketplace Compared
• Cursor Alternative
• Local Whisper + Piper
• Custom AI Dashboard
• Community Hub