registry/registry/coder-labs/modules/codex/README.md

display_name	icon	description	verified	tags
Codex CLI	../../../../.icons/openai.svg	Run Codex CLI in your workspace with AgentAPI integration	true	agent codex ai openai tasks aibridge

Codex CLI

Run Codex CLI in your workspace to access OpenAI's models through the Codex interface, with custom pre/post install scripts. This module integrates with AgentAPI for Coder Tasks compatibility.

module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "4.2.0"
  agent_id       = coder_agent.example.id
  openai_api_key = var.openai_api_key
  workdir        = "/home/coder/project"
}

Prerequisites

• OpenAI API key for Codex access

Examples

Run standalone

module "codex" {
  count          = data.coder_workspace.me.start_count
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "4.2.0"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  workdir        = "/home/coder/project"
  report_tasks   = false
}

Usage with AI Bridge

AI Bridge is a Premium Coder feature that provides centralized LLM proxy management. To use AI Bridge, set enable_aibridge = true. Requires Coder version 2.30+

For tasks integration with AI Bridge, add enable_aibridge = true to the Usage with Tasks example below.

Standalone usage with AI Bridge

module "codex" {
  source          = "registry.coder.com/coder-labs/codex/coder"
  version         = "4.2.0"
  agent_id        = coder_agent.example.id
  workdir         = "/home/coder/project"
  enable_aibridge = true
}

When enable_aibridge = true, the module:

• Configures Codex to use the AI Bridge profile with base_url pointing to ${data.coder_workspace.me.access_url}/api/v2/aibridge/openai/v1 and env_key pointing to the workspace owner's session token

profile = "aibridge" # sets the default profile to aibridge

[model_providers.aibridge]
name = "AI Bridge"
base_url = "https://example.coder.com/api/v2/aibridge/openai/v1"
env_key = "CODER_AIBRIDGE_SESSION_TOKEN"
wire_api = "responses"

[profiles.aibridge]
model_provider = "aibridge"
model = "<model>" # as configured in the module input
model_reasoning_effort = "<model_reasoning_effort>" # as configured in the module input

This allows Codex to route API requests through Coder's AI Bridge instead of directly to OpenAI's API. Template build will fail if openai_api_key is provided alongside enable_aibridge = true.

Usage with Tasks

This example shows how to configure Codex with Coder tasks.

resource "coder_ai_task" "task" {
  count  = data.coder_workspace.me.start_count
  app_id = module.codex.task_app_id
}

data "coder_task" "me" {}

module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "4.2.0"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  ai_prompt      = data.coder_task.me.prompt
  workdir        = "/home/coder/project"

  # Optional: route through AI Bridge (Premium feature)
  # enable_aibridge = true
}

Advanced Configuration

This example shows additional configuration options for custom models, MCP servers, and base configuration.

module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "4.2.0"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  workdir        = "/home/coder/project"

  codex_version = "0.1.0"  # Pin to a specific version
  codex_model   = "gpt-4o" # Custom model

  # Override default configuration
  base_config_toml = <<-EOT
    sandbox_mode = "danger-full-access"
    approval_policy = "never"
    preferred_auth_method = "apikey"
  EOT

  # Add extra MCP servers
  additional_mcp_servers = <<-EOT
    [mcp_servers.GitHub]
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-github"]
    type = "stdio"
  EOT
}

Warning

This module configures Codex with a workspace-write sandbox that allows AI tasks to read/write files in the specified workdir. While the sandbox provides security boundaries, Codex can still modify files within the workspace. Use this module only in trusted environments and be aware of the security implications.

How it Works

• Install: The module installs Codex CLI and sets up the environment
• System Prompt: If codex_system_prompt is set, writes the prompt to AGENTS.md in the ~/.codex/ directory
• Start: Launches Codex CLI in the specified directory, wrapped by AgentAPI
• Configuration: Sets OPENAI_API_KEY environment variable and passes --model flag to Codex CLI (if variables provided)
• Session Continuity: When continue = true (default), the module automatically tracks task sessions in ~/.codex-module/.codex-task-session. On workspace restart, it resumes the existing session with full conversation history. Set continue = false to always start fresh sessions.

State Persistence

AgentAPI can save and restore its conversation state to disk across workspace restarts. This complements continue (which resumes the Codex CLI session) by also preserving the AgentAPI-level context. Enabled by default, requires agentapi >= v0.12.0 (older versions skip it with a warning).

To disable:

module "codex" {
  # ... other config
  enable_state_persistence = false
}

Configuration

Default Configuration

When no custom base_config_toml is provided, the module uses these secure defaults:

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

[sandbox_workspace_write]
network_access = true

Note

If no custom configuration is provided, the module uses secure defaults. The Coder MCP server is always included automatically. For containerized workspaces (Docker/Kubernetes), you may need sandbox_mode = "danger-full-access" to avoid permission issues. For advanced options, see Codex config docs.

Troubleshooting

• Check installation and startup logs in ~/.codex-module/
• Ensure your OpenAI API key has access to the specified model

Important

To use tasks with Codex CLI, ensure you have the openai_api_key variable set. Tasks Template Example. The module automatically configures Codex with your API key and model preferences. workdir is a required variable for the module to function correctly.

References

• Codex CLI Documentation
• AgentAPI Documentation
• Coder AI Agents Guide
• AI Bridge