Understanding Codex: Agents, Sandbox, Approval, AGENTS.md, and Memory

On the first day using Codex, the author asked it to rename three files. The tool changed only files inside the project directory, leaving desktop files untouched, which led to the discovery that Codex operates inside a sandbox that restricts its actions to a defined workspace.

Agent (Agent)

Codex is an OpenAI programming agent that can read code, modify files, and run commands autonomously. The official description says the agent runs a loop that executes terminal commands, then checks and validates its work. In plain terms the loop is think → do → see :

Think : read relevant files, examine errors, understand the situation.

Do : edit code, create files, run commands.

See : run tests, view output, and repeat if necessary.

Compared to a simple chatbot that only returns text, the agent is like a personal shopper that can browse, compare, order, and verify a product without further user input.

Sandbox (Sandbox)

The sandbox defines the technical boundary within which Codex can act. It decides which files can be modified and whether network access is allowed. Three sandbox modes are provided: read-only – cannot modify any files and cannot access the network. Use when you only want Codex to read code or propose plans. workspace-write – can modify files **only inside the specified workspace**; network access is disabled by default. This is the most common mode for daily development. danger-full-access – full machine access, including network. Intended for trusted environments; use with caution.

The sandbox also restricts commands spawned by Codex (e.g., git, package managers, test scripts) to the same boundary.

Implementation varies by platform:

macOS – uses the built‑in Seatbelt framework.

Windows – runs in the native Windows sandbox.

Linux / WSL2 – requires the external bubblewrap tool.

Approval (Approval)

When Codex attempts to step outside the sandbox, an approval policy determines whether it must ask the user. Three policies are documented: untrusted – commands not in a trusted set trigger a prompt. on-request – the default balance; Codex works inside the sandbox freely and only prompts when it needs to exit. never – no prompts; fully automatic, typically paired with danger-full-access.

Two common combinations are recommended:

Low‑risk local automation (default): sandbox_mode = "workspace-write" and approval_policy = "on-request".

Full access (use with extreme caution): sandbox_mode = "danger-full-access" and approval_policy = "never".

AGENTS.md (Project Handbook)

AGENTS.md is a plain‑text file that serves as a project‑specific handbook. Codex reads it before starting work and follows the rules inside. Typical entries include build/test commands, code‑review expectations, and repository‑specific conventions.

Placement hierarchy determines precedence:

Global: ~/.codex/AGENTS.md – applies to all projects for the user.

Project: AGENTS.md in the repository root or a subdirectory – overrides the global file and can be version‑controlled.

Using AGENTS.md as a feedback loop lets Codex automatically record corrections. The author’s two‑week experiment grew the file to about twenty lines, eliminating repeated mistakes in new sessions.

Memory and Chronicle

Memory lets Codex retain useful information from previous conversations (e.g., tech stack, project conventions). Key facts:

Off by default; enable by setting memories = true in ~/.codex/config.toml or via the app settings.

Unavailable in the European Economic Area, the UK, and Switzerland.

Updates only after a session has been idle long enough.

Stored locally under ~/.codex/memories/.

Can be toggled per session with the /memories command.

Chronicle is an experimental preview (macOS, ChatGPT Pro only) that feeds screen‑content (open files, PRs, docs) into Codex. It consumes quota quickly, raises prompt‑injection risk, and stores data unencrypted locally. Users are advised to pause it in sensitive contexts.

Hands‑On Experiment: Seeing the Sandbox Block

The author provides a minimal four‑step experiment to observe sandbox behavior:

Create an empty directory and start Codex:

mkdir -p ~/codex-demo && cd ~/codex-demo
codex

Switch to read‑only mode via /permissions and select “Read Only”.

Ask Codex to create hello.txt with content “hello codex”. In read‑only mode Codex pauses and asks for approval.

Change to workspace-write mode and repeat the request; Codex creates the file without prompting.

This demonstrates that the same write request is blocked in read-only but allowed in workspace-write, confirming the sandbox‑plus‑approval interaction.

Summary of Core Concepts

Agent : an autonomous “think → do → see” AI, not a simple chat interface.

Sandbox : the permission circle that limits which files can be changed and whether network access is allowed.

Approval : the separate knob that decides whether Codex must ask before crossing the sandbox boundary.

AGENTS.md : a project‑specific handbook that Codex reads before acting.

Memory / Chronicle : optional layers that let Codex retain conversation context (Memory) or screen context (Chronicle), with the latter being experimental and riskier.

With these concepts understood, users can predict why Codex sometimes refuses to modify a file, why it may pause for approval, and how to configure the tool for safe and efficient automation.