Codex CLI

Install and configure the Codex CLI in your workspace.

module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "5.1.0"
  agent_id       = coder_agent.main.id
  openai_api_key = var.openai_api_key
}

Warning

If upgrading from v4.x.x of this module: v5 is a major refactor that drops support for Coder Tasks and Boundary. v5 also assumes npm is pre-installed; it no longer bootstraps Node.js. Keep using v4.x.x if you depend on them. See the PR description for a full migration guide.

Examples

Standalone mode with a launcher app

locals {
  codex_workdir = "/home/coder/project"
}

module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "5.1.0"
  agent_id       = coder_agent.main.id
  workdir        = local.codex_workdir
  openai_api_key = var.openai_api_key
}

resource "coder_app" "codex" {
  agent_id     = coder_agent.main.id
  slug         = "codex"
  display_name = "Codex"
  icon         = "/icon/openai.svg"
  open_in      = "slim-window"
  command      = <<-EOT
    #!/bin/bash
    set -e
    cd "${local.codex_workdir}"
    codex
  EOT
}

Note

The coder_app command re-executes on every pane reconnect. This works for interactive codex (which stays alive), but one-shot commands like codex exec will re-run each time. For one-shot prompts, use a coder_script (runs once at startup) and a coder_app that attaches to the existing session (e.g. via tmux/screen).

Usage with AI Gateway

AI Gateway is a Premium Coder feature that provides centralized LLM proxy management. Requires Coder >= 2.30.0.

module "codex" {
  source            = "registry.coder.com/coder-labs/codex/coder"
  version           = "5.1.0"
  agent_id          = coder_agent.main.id
  workdir           = "/home/coder/project"
  enable_ai_gateway = true
}

When enable_ai_gateway = true, the module configures Codex to use the aigateway model provider in config.toml with the workspace owner's session token for authentication.

Caution

enable_ai_gateway = true is mutually exclusive with openai_api_key. Setting both fails at plan time.

Note

If you provide a custom base_config_toml, the module writes it verbatim and does not inject model_provider = "aigateway" automatically. Add it to your config yourself:
model_provider = "aigateway"

Advanced Configuration

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

  codex_version = "0.128.0"

  base_config_toml = <<-EOT
    sandbox_mode = "danger-full-access"
    approval_policy = "never"
    preferred_auth_method = "apikey"
  EOT

  mcp = <<-EOT
    [mcp_servers.GitHub]
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-github"]
    type = "stdio"
  EOT

  mcp_config_remote_path = [
    "https://example.com/team-mcp-servers.toml",
    "https://raw.githubusercontent.com/your-org/your-repo/main/.codex/mcp.toml",
  ]
}

Note

Servers configured through mcp or mcp_config_remote_path are appended to ~/.codex/config.toml, so they apply to every Codex session in the workspace. Each remote URL should return a body in Codex's native TOML format, e.g.:
[mcp_servers.my-tool]
command = "my-tool-server"
args = ["--port", "8080"]
type = "stdio"
Fetch failures (network errors or non-2xx responses) log a warning and the install continues with the remaining URLs. Bodies are appended verbatim without further validation, so make sure the URL returns valid Codex TOML.

Serialize a downstream `coder_script` after the install pipeline

The module exposes the scripts output: an ordered list of coder exp sync names for the scripts this module creates (pre_install, install, post_install). Scripts that were not configured are absent.

module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
  version        = "5.1.0"
  agent_id       = coder_agent.main.id
  openai_api_key = var.openai_api_key
}

resource "coder_script" "post_codex" {
  agent_id     = coder_agent.main.id
  display_name = "Run after Codex install"
  run_on_start = true
  script       = <<-EOT
    #!/bin/bash
    set -euo pipefail
    trap 'coder exp sync complete post-codex' EXIT
    coder exp sync want post-codex ${join(" ", module.codex.scripts)}
    coder exp sync start post-codex

    codex --version
  EOT
}

Configuration

When no custom base_config_toml is provided, the module uses a minimal default with preferred_auth_method = "apikey". For advanced options, see Codex config docs.

Troubleshooting

Check the log files in ~/.coder-modules/coder-labs/codex/logs/ for detailed information.

cat ~/.coder-modules/coder-labs/codex/logs/install.log
cat ~/.coder-modules/coder-labs/codex/logs/pre_install.log
cat ~/.coder-modules/coder-labs/codex/logs/post_install.log

5.6 KiB Raw Blame History