---
title: Run OpenAI Codex CLI
description: "Use OpenAI's Codex CLI agent in an isolated sandbox environment."
---

# Run OpenAI Codex CLI

OpenAI's [Codex CLI](https://github.com/openai/codex) is a terminal-based coding agent. This recipe sets it up in an isolated Caged sandbox.

## Prerequisites

- Caged CLI installed (`brew install caged-dev/tap/caged` or `curl -fsSL https://get.caged.dev | sh`)
- Caged account with API key (`caged login`)
- An `OPENAI_API_KEY` stored in your Caged secrets

## Quick Start Examples

### Basic: Sandbox with Codex

```bash
# Create sandbox with Codex pre-installed
caged up --template node-20 --agents codex

# Connect to the sandbox
caged connect cage_xxxxx

# Inside the sandbox, Codex is ready
caged> codex "What files are in this directory?"
```

### Clone a Repo + Codex

```bash
# Clone your repo and install Codex
caged up \
  --template node-20 \
  --repo https://github.com/your-org/your-project \
  --agents codex \
  --env "OPENAI_API_KEY=$OPENAI_API_KEY"

# Connect and start working
caged connect cage_xxxxx
caged> codex "Refactor the authentication module to use JWT"
```

### Full Example with All Options

```bash
caged up \
  --template node-20 \
  --cpus 2 \
  --memory 2048 \
  --repo https://github.com/your-org/your-project \
  --budget 10 \
  --agents codex \
  --env "OPENAI_API_KEY=$OPENAI_API_KEY"
```

<Tip>
The `--agents codex` flag automatically installs `@openai/codex` globally.
</Tip>

## Option 2: Config File

```yaml
# .caged.yaml
template: node-20
resources:
  cpu: 2
  memory: 2048
  disk: 10
timeout: 3600
budget: 10.00

agents:
  - codex

secrets:
  - OPENAI_API_KEY

network_mode: allowlist
allowed_hosts:
  - api.openai.com
  - registry.npmjs.org
  - github.com
```

```bash
caged up
```

## Option 3: API

```bash
SANDBOX_ID=$(curl -s -X POST https://api.caged.dev/v1/sandboxes \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "node-20",
    "cpus": 2,
    "memory_mb": 2048,
    "repo": "https://github.com/your-org/your-project",
    "budget": 10.00,
    "agents": ["codex"],
    "secrets": ["OPENAI_API_KEY"]
  }' | jq -r '.id')

# Execute Codex
curl -X POST "https://api.caged.dev/v1/sandboxes/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer caged_sk_..." \
  -d '{"command": "codex \"Add comprehensive error handling to all API routes\""}'
```

## Running Multiple Agents

You can install multiple agents in the same sandbox:

```bash
caged run \
  --template node-20 \
  --agents codex,claude-code \
  --env "OPENAI_API_KEY=$OPENAI_API_KEY,ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY"
```

This lets you compare outputs or use different agents for different tasks.

## Tips

<Tip>
**Model selection**: Codex uses GPT-4 by default. Check OpenAI docs for available models.
</Tip>

<Tip>
**Sandbox isolation**: Even if the agent tries to access external services, the network allowlist restricts it to approved hosts only.
</Tip>