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

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.0.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.0.0"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  workdir        = "/home/coder/project"
  report_tasks   = false
}

Tasks integration

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.0.0"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  ai_prompt      = data.coder_task.me.prompt
  workdir        = "/home/coder/project"

  # Custom configuration for full auto mode
  base_config_toml = <<-EOT
    approval_policy = "never"
    preferred_auth_method = "apikey"
  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.

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

Custom Configuration

For custom Codex configuration, use base_config_toml and/or additional_mcp_servers:

module "codex" {
  source  = "registry.coder.com/coder-labs/codex/coder"
  version = "4.0.0"
  # ... other variables ...

  # 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
}

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