Co-authored-by: DevelopmentCats <christofer@coder.com>

2025-08-19 19:24:45 +05:00

5.3 KiB

Raw Blame History

display_name

icon

description

verified

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        = "1.0.1"
  agent_id       = coder_agent.example.id
  openai_api_key = var.openai_api_key
  folder         = "/home/coder/project"
}

Prerequisites

You must add the Coder Login module to your template
OpenAI API key for Codex access

Usage Example

Simple usage Example:

module "codex" {
  count               = data.coder_workspace.me.start_count
  source              = "registry.coder.com/coder-labs/codex/coder"
  version             = "1.0.1"
  agent_id            = coder_agent.example.id
  openai_api_key      = "..."
  codex_model         = "o4-mini"
  install_codex       = true
  codex_version       = "latest"
  folder              = "/home/coder/project"
  codex_system_prompt = "You are a helpful coding assistant. Start every response with `Codex says:`"
}

Example usage with Tasks:

# This
data "coder_parameter" "ai_prompt" {
  type        = "string"
  name        = "AI Prompt"
  default     = ""
  description = "Initial prompt for the Codex CLI"
  mutable     = true
}

module "coder-login" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/coder-login/coder"
  version  = "1.0.31"
  agent_id = coder_agent.example.id
}

module "codex" {
  source          = "registry.coder.com/coder-labs/codex/coder"
  agent_id        = coder_agent.example.id
  openai_api_key  = "..."
  ai_prompt       = data.coder_parameter.ai_prompt.value
  folder          = "/home/coder/project"
  approval_policy = "never" # Full auto mode
}

Warning

Security Notice: This module configures Codex with a workspace-write sandbox that allows AI tasks to read/write files in the specified folder. While the sandbox provides security boundaries, Codex can still modify files within the workspace. Use this module 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 and folder are set, creates the directory (if needed) and writes the prompt to AGENTS.md
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)

Sandbox Configuration

The module automatically configures Codex with a secure sandbox that allows AI tasks to work effectively:

Sandbox Mode: workspace-write - Allows Codex to read/write files in the specified folder
Approval Policy: on-request - Codex asks for permission before performing potentially risky operations
Network Access: Enabled within the workspace for package installation and API calls

Customizing Sandbox Behavior

You can customize the sandbox behavior using dedicated variables:

Using Dedicated Variables (Recommended)

For most use cases, use the dedicated sandbox variables:

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

  # Containerized environments (fixes Landlock errors)
  sandbox_mode = "danger-full-access"

  # Or for read-only mode
  # sandbox_mode = "read-only"

  # Or for full auto mode
  # approval_policy = "never"

  # Or disable network access
  # network_access = false
}

Using extra_codex_settings_toml (Advanced)

For advanced configuration or when you need to override multiple settings:

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

  extra_codex_settings_toml = <<-EOT
    # Any custom Codex configuration
    model = "gpt-4"
    disable_response_storage = true
  EOT
}

Note

The dedicated variables (sandbox_mode, approval_policy, network_access) are the recommended way to configure sandbox behavior. Use extra_codex_settings_toml only for advanced configuration that isn't covered by the dedicated variables.

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, and you create a coder_parameter named "AI Prompt" and pass its value to the codex module's ai_prompt variable. Tasks Template Example. The module automatically configures Codex with your API key and model preferences. folder is a required variable for the module to function correctly.

5.3 KiB Raw Blame History