Codex

codex is a pre-built AI Agents runtime environment that includes OpenAI Codex CLI. It can automatically generate, modify, and execute code in an isolated sandbox environment with full file system, terminal, and git access.

The template comes pre-installed with common tools such as Node.js, git, ripgrep, vim, GitHub CLI, and frontend scaffolding tools like pnpm/tsx/vite. No API keys are built into the image; authentication information is injected via envs when creating the sandbox or through secret injection rules.

Template Contents

Component	Description
codex	OpenAI Codex CLI
Basic Tools	Node.js 24.x, git, ripgrep, vim, GitHub CLI, pnpm/tsx/vite, etc.

Creating a Sandbox

Pass OPENAI_API_KEY via envs:

import { Sandbox } from 'e2b'

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

Common CLI Flags

Flag	Description
exec "<prompt>"	Entry subcommand for headless (non-interactive) mode
--full-auto	Automatically approve tool calls; available in sandboxed environments
--skip-git-repo-check	Skip git repository ownership check
-C <path>	Specify working directory
--json	Output real-time JSONL event stream
--output-schema <path>	Constrain output format with JSON Schema
--image <path>	Pass an image as visual context (screenshots, design mockups, etc.)

Headless Execution

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('codex', {
  envs: { OPENAI_API_KEY: process.env.OPENAI_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()

Git Repository Integration

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"`,
)

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

Streaming Events

Using --json outputs structured events line by line, making it easy for programs to consume:

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

Schema-Constrained Output

Write the expected output structure as a JSON Schema file, then pass it to the CLI via --output-schema to obtain stable structured results:

await sandbox.files.write(
  '/home/user/schema.json',
  JSON.stringify({
    type: 'object',
    properties: {
      issues: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            file: { type: 'string' },
            severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
          },
          required: ['file', 'severity'],
        },
      },
    },
    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 "List all security issues"`,
)

Image Input

Upload a mockup to the sandbox and use --image to let Codex turn the visual design into code:

import fs from 'node:fs'

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 React"`,
)

Using with Secret Injection

To keep the real OPENAI_API_KEY on the platform side, create an injection rule of type openai (see Secret Injection), and pass only a placeholder in the sandbox:

const sandbox = await Sandbox.create('codex', {
  envs: { OPENAI_API_KEY: 'placeholder' },
  injections: [{ id: '<rule-id>' }],
})

If you need to point to an OpenAI-compatible gateway, explicitly set base_url in the injection rule. Replace the example host with your actual gateway host, and keep the Codex base_url value consistent with the injection rule.

Using an OpenAI-Compatible Gateway

To have Codex CLI call an OpenAI-compatible third-party gateway, pass the gateway key via CODEX_API_KEY and configure a custom model_provider.

Method 1: Write to ~/.codex/config.toml inside the sandbox. Suitable for scenarios requiring multiple executions or reusable configuration.

model_provider = "custom"
model = "openai/gpt-5"

approval_policy = "never"
sandbox_mode = "workspace-write"

[model_providers.custom]
name = "Custom"
base_url = "https://api.example.com/bypass/openai/v1"
env_key = "CODEX_API_KEY"
wire_api = "responses"

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

const configContent = `\
model_provider = "custom"
model = "openai/gpt-5"

approval_policy = "never"
sandbox_mode = "workspace-write"

[model_providers.custom]
name = "Custom"
base_url = "https://api.example.com/bypass/openai/v1"
env_key = "CODEX_API_KEY"
wire_api = "responses"
`

try {
  await sandbox.commands.run('mkdir -p ~/.codex')
  await sandbox.files.write('/home/user/.codex/config.toml', configContent)

  const result = await sandbox.commands.run('codex exec --skip-git-repo-check "Hi"')
  console.log(result.stdout)
} finally {
  await sandbox.kill()
}

Method 2: Pass configuration via CLI flags. Suitable for one-time calls or when you prefer not to write a configuration file.

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

try {
  const result = await sandbox.commands.run(
    'codex exec' +
      ' -c model_provider="custom"' +
      ' -m "openai/gpt-5"' +
      ' -c approval_policy="never"' +
      ' -s workspace-write' +
      ' -c \'model_providers.custom.name="Custom"\'' +
      ' -c \'model_providers.custom.base_url="https://api.example.com/bypass/openai/v1"\'' +
      ' -c \'model_providers.custom.env_key="CODEX_API_KEY"\'' +
      ' -c \'model_providers.custom.wire_api="responses"\'' +
      ' --skip-git-repo-check "Hi"',
  )
  console.log(result.stdout)
} finally {
  await sandbox.kill()
}

References

• Codex CLI Project Homepage: https://github.com/openai/codex