Skip to main content
Codex is OpenAI’s open-source coding agent. E2B provides a pre-built codex template with Codex already installed.

CLI

Create a sandbox with the E2B CLI.
Once inside the sandbox, start Codex.

Setup

The SDK examples below need two API keys in your environment:
  • E2B_API_KEY: your E2B API key.
  • CODEX_API_KEY: an OpenAI API key. The examples pass it into the sandbox, where Codex reads it.
Install the SDK. The TypeScript examples use top-level await, so the project must be an ES module.
Each example checks the key before it creates a sandbox, and kills the sandbox in a finally block (a with block in Python), so a failed run does not leave the sandbox running until it times out. Agent runs take minutes, so every Codex command passes timeoutMs: 0 (timeout=0 in Python): the SDK stops a command after 60 seconds by default. The sandbox’s own timeoutMs (timeout) is how long the sandbox lives, which is a separate limit.

Run headless

Use codex exec for non-interactive mode and --dangerously-bypass-approvals-and-sandbox to auto-approve tool calls and turn off Codex’s own command sandbox, which blocks network access and writes outside the working folder. The E2B sandbox isolates the agent from your host machine, but sandboxes can reach the open internet by default. Restrict outbound traffic with network rules. Pass --skip-git-repo-check to bypass git directory ownership checks inside the sandbox. Pass CODEX_API_KEY as an environment variable.
Auto-approving tool calls is contained by the E2B sandbox: the agent cannot touch your host machine, local files, or credentials. It can still make outbound network requests — internet access is enabled by default. To limit where an auto-approved agent can connect, configure outbound network rules (allowInternetAccess, plus allow/deny lists by CIDR or hostname). Hostname rules apply to HTTP(S) traffic only; use CIDR rules for other protocols.
Codex writes files inside the sandbox. Read them back with sandbox.files.read(), or run git diff as in the next example.

Example: work on a cloned repository

Clone a repository, then use -C to set Codex’s working directory to it. The example clones a public repository. For a private one, put a token in the URL (https://x-access-token:$GITHUB_TOKEN@github.com/<owner>/<repo>.git) and pass GITHUB_TOKEN in the envs of that commands.run call.

Schema-validated output

Use --output-schema to constrain the agent’s final response to a JSON Schema. This ensures the output conforms to a specific structure — useful for building reliable pipelines. OpenAI only accepts strict schemas: every object needs "additionalProperties": false, and every property must be listed in required.

Streaming events

Use --json to get a JSONL event stream. Each line is a JSON object representing an agent event (tool calls, file changes, messages). Progress goes to stderr; events go to stdout. Output arrives in chunks that can end mid-line (a large command output is one long event), so buffer the stream and parse only complete lines.

Resume a session

Codex persists sessions (rollout files under ~/.codex/sessions in the sandbox) that can be resumed with follow-up tasks using codex exec resume. Run the first task with --json and capture the thread_id from the thread.started event.
To simply continue the most recent session in the working directory, use codex exec resume --last "follow-up task" — no thread ID needed. When working in a cloned repo, pass -C before the resume subcommand (codex exec -C /home/user/repo resume <thread_id> "..."); it is not accepted after it.

Image input

Pass screenshots or design mockups with --image to give Codex visual context alongside the prompt. The example reads mockup.png from your current directory. --image takes a list of files, so put it after the prompt.

Build a custom template

If you need to customize the environment (e.g. pre-install dependencies, add config files), build your own template on top of the pre-built codex template.
Run the build script to create the template.

Sandbox persistence

Auto-pause, resume, and manage sandbox lifecycle

SSH access

Connect to the sandbox via SSH for interactive sessions