codex template with Codex already installed.
CLI
Create a sandbox with the E2B CLI.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.
await, so the project must be an ES module.
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
Usecodex 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.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.
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-builtcodex template.
Related guides
Sandbox persistence
Auto-pause, resume, and manage sandbox lifecycle
SSH access
Connect to the sandbox via SSH for interactive sessions