Introduction
OpenAI Codex represents a different philosophy from Claude Code. Where Claude Code runs locally on your machine, Codex runs in isolated cloud sandboxes. This chapter explores how Codex works and what we can learn from its architecture.
The Cloud-Native Approach: Codex embraces isolation and parallelism. Each task runs in its own container with full internet access and long-running capabilities. The tradeoff: you work with your code through git, not your local filesystem.
What is Codex
Codex is OpenAI's agentic coding assistant that runs in sandboxed cloud environments. Key characteristics:
- Cloud execution: Tasks run in isolated containers
- Git-based: Clones your repos, pushes changes via git
- Parallel tasks: Multiple codex instances can run simultaneously
- Internet access: Can browse documentation, search, fetch APIs
- Long-running: Tasks can run for hours autonomously
- Powered by o3: Uses OpenAI's reasoning model for complex decisions
📝codex_usage.txt
1# Assign a task to Codex
2$ codex task "Implement user authentication with OAuth2"
3
4# Codex will:
5# 1. Clone your repository
6# 2. Analyze the codebase
7# 3. Research OAuth2 best practices (using internet)
8# 4. Implement the feature
9# 5. Write tests
10# 6. Create a pull request
11
12# Check task status
13$ codex status task-abc123
14
15# View what Codex is doing
16$ codex logs task-abc123Architecture Overview
📝codex_architecture.txt
1┌────────────────────────────────────────────────────────────────┐
2│ CODEX PLATFORM │
3├────────────────────────────────────────────────────────────────┤
4│ │
5│ ┌─────────────────┐ ┌────────────────────────────────────┐ │
6│ │ User/API │───▶│ Task Orchestrator │ │
7│ │ Interface │ │ (Queue, Schedule, Monitor) │ │
8│ └─────────────────┘ └───────────────┬────────────────────┘ │
9│ │ │
10│ ┌──────────────────────────────────────▼────────────────────┐ │
11│ │ SANDBOX MANAGER │ │
12│ │ Creates isolated containers for each task │ │
13│ └──────────────────────────────────────┬────────────────────┘ │
14│ │ │
15│ ┌──────────────────────────────────────▼────────────────────┐ │
16│ │ SANDBOX INSTANCE (per task) │ │
17│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │
18│ │ │ Git │ │ Browser │ │ Shell │ │ Agent (codex-1) │ │ │
19│ │ │ Client │ │ Access │ │ (bash) │ │ powered by o3 │ │ │
20│ │ └─────────┘ └─────────┘ └─────────┘ └─────────────────┘ │ │
21│ │ │ │
22│ │ ┌───────────────────────────────────────────────────┐ │ │
23│ │ │ Persistent Workspace │ │ │
24│ │ │ (cloned repo, installed deps, state) │ │ │
25│ │ └───────────────────────────────────────────────────┘ │ │
26│ └───────────────────────────────────────────────────────────┘ │
27│ │
28└────────────────────────────────────────────────────────────────┘Core Components
| Component | Purpose | Key Feature |
|---|---|---|
| Task Orchestrator | Manages task lifecycle | Queuing, scheduling, status tracking |
| Sandbox Manager | Creates isolated environments | Container provisioning, resource limits |
| Agent (codex-1) | Reasoning and execution | Powered by o3 with extended thinking |
| Persistent Workspace | Task state and files | Survives across agent iterations |
Cloud-Native Design
Why Cloud-Based?
- Isolation: Tasks can't affect your local system or each other
- Parallelism: Run multiple tasks simultaneously
- Internet: Full access to documentation, APIs, package registries
- Long-running: Tasks can run for hours without tying up your machine
- Reproducibility: Clean environment for each task
The Git-Based Workflow
📝git_workflow.txt
1User Request: "Add pagination to the API"
2
31. CLONE
4 └─ git clone user-repo
5 └─ Install dependencies
6 └─ Run existing tests (baseline)
7
82. WORK
9 └─ Agent analyzes codebase
10 └─ Agent makes changes
11 └─ Agent runs tests
12 └─ Agent iterates until passing
13
143. DELIVER
15 └─ git checkout -b feat/pagination
16 └─ git commit -m "Add pagination support"
17 └─ git push origin feat/pagination
18 └─ Create pull request
19
204. CLEANUP
21 └─ Sandbox is archived
22 └─ Logs are preserved
23 └─ Resources are releasedWorkspace Persistence
Unlike ephemeral functions, Codex workspaces persist across agent iterations:
🐍workspace_concept.py
1# Conceptual workspace management
2class CodexWorkspace:
3 def __init__(self, repo_url: str, task_id: str):
4 self.repo_url = repo_url
5 self.task_id = task_id
6 self.workspace_path = f"/workspaces/{task_id}"
7
8 def setup(self):
9 # Clone repository
10 subprocess.run(["git", "clone", self.repo_url, self.workspace_path])
11
12 # Install dependencies
13 os.chdir(self.workspace_path)
14 if Path("package.json").exists():
15 subprocess.run(["npm", "install"])
16 elif Path("requirements.txt").exists():
17 subprocess.run(["pip", "install", "-r", "requirements.txt"])
18
19 def persist(self):
20 # Workspace survives across agent calls
21 # State, installed packages, modified files all persist
22 pass
23
24 def cleanup(self):
25 # Archive workspace after task completion
26 archive_path = f"/archives/{self.task_id}"
27 shutil.move(self.workspace_path, archive_path)Codex vs Claude Code
| Aspect | OpenAI Codex | Claude Code |
|---|---|---|
| Execution | Cloud sandbox | Local machine |
| File access | Cloned repo only | Full filesystem |
| Internet | Full access | Limited by default |
| Parallelism | Multiple concurrent tasks | Sequential |
| Duration | Hours to days | Interactive session |
| Delivery | Pull requests | Direct file changes |
| Model | codex-1 (o3-based) | Claude Sonnet/Opus |
| Privacy | Code sent to cloud | Stays local |
When to Use Each
- Use Codex: Long-running tasks, research-heavy work, when you want PRs
- Use Claude Code: Quick changes, local-only code, interactive development
- Use both: Codex for big features, Claude Code for iteration on PRs
Complementary Tools
Many developers use both: Codex for initial implementation of complex features, Claude Code for quick iterations and fixes once code is local.
Summary
Codex's architecture teaches us:
- Cloud-native: Sandbox isolation enables safety and parallelism
- Git-based: Code moves through version control, not filesystems
- Long-running: Tasks can span hours with persistent workspaces
- o3-powered: Reasoning model enables complex decision-making
- Different tradeoffs: Cloud vs local, PRs vs direct changes
Next: Let's dive deeper into Codex's sandboxed execution model and how it enables safe, powerful agent behavior.