Skip to main content

Documentation Index

Fetch the complete documentation index at: https://e2b.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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. 
e2b sbx create codex
Once inside the sandbox, start Codex. 
codex

​
Run headless

Use codex exec for non-interactive mode and --full-auto to auto-approve tool calls (safe inside E2B sandboxes). Pass --skip-git-repo-check to bypass git directory ownership checks inside the sandbox. Pass CODEX_API_KEY as an environment variable. 
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
})

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check "Create a hello world HTTP server in Go"`
)

console.log(result.stdout)
await sandbox.kill()

​
Example: work on a cloned repository

Use -C to set Codex’s working directory to a cloned repo. 
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
  timeoutMs: 600_000,
})

await sandbox.git.clone('https://github.com/your-org/your-repo.git', {
  path: '/home/user/repo',
  username: 'x-access-token',
  password: process.env.GITHUB_TOKEN,
  depth: 1,
})

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check -C /home/user/repo "Add error handling to all API endpoints"`,
  { onStdout: (data) => process.stdout.write(data) }
)

const diff = await sandbox.commands.run('cd /home/user/repo && git diff')
console.log(diff.stdout)

await sandbox.kill()

​
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. 
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
})

await sandbox.files.write('/home/user/schema.json', JSON.stringify({
  type: 'object',
  properties: {
    issues: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          file: { type: 'string' },
          line: { type: 'number' },
          severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
          description: { type: 'string' },
        },
        required: ['file', 'severity', 'description'],
      },
    },
  },
  required: ['issues'],
}))

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check --output-schema /home/user/schema.json -C /home/user/repo "Review this codebase for security issues"`
)

const response = JSON.parse(result.stdout)
console.log(response.issues)

await sandbox.kill()

​
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. 
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
})

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check --json -C /home/user/repo "Refactor the utils module into separate files"`,
  {
    onStdout: (data) => {
      for (const line of data.split('\n').filter(Boolean)) {
        const event = JSON.parse(line)
        console.log(`[${event.type}]`, event)
      }
    },
  }
)

await sandbox.kill()

​
Image input

Pass screenshots or design mockups with --image to give Codex visual context alongside the prompt. 
import fs from 'fs'
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { CODEX_API_KEY: process.env.CODEX_API_KEY },
  timeoutMs: 600_000,
})

// Upload a design mockup to the sandbox
await sandbox.files.write(
  '/home/user/mockup.png',
  fs.readFileSync('./mockup.png')
)

const result = await sandbox.commands.run(
  `codex exec --full-auto --skip-git-repo-check --image /home/user/mockup.png -C /home/user/repo "Implement this UI design as a React component"`,
  { onStdout: (data) => process.stdout.write(data) }
)

await sandbox.kill()

​
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. 
// template.ts
import { Template } from 'e2b'

export const template = Template()
  .fromTemplate('codex')

// build.ts
import { Template, defaultBuildLogger } from 'e2b'
import { template as codexTemplate } from './template'

await Template.build(codexTemplate, 'my-codex', {
  cpuCount: 2,
  memoryMB: 2048,
  onBuildLogs: defaultBuildLogger(),
})
Run the build script to create the template. 
npx tsx build.ts

Sandbox persistence

Auto-pause, resume, and manage sandbox lifecycle

Git integration

Clone repos, manage branches, and push changes

SSH access

Connect to the sandbox via SSH for interactive sessions