How to Set Up Codex CLI with FreeLLMAPI: A Complete Configuration Guide

FreeLLMAPI provides a zero-persistence setup-codex command that automatically generates a working Codex CLI configuration at ~/.codex/config.toml, binding to the unified endpoint at http://localhost:3001/v1 while keeping your API key in environment variables.

Configuring OpenAI's Codex CLI to work with third-party providers typically requires manual TOML editing, but FreeLLMAPI automates the entire process. According to the tashfeenahmed/freellmapi source code, the repository ships with a dedicated generator that creates provider-specific configurations and handles model selection automatically. This guide explains how to use the setup-codex command to connect Codex CLI to FreeLLMAPI's aggregated model router in under a minute.

Understanding the setup-codex Generator

FreeLLMAPI ships a generator called setup-codex that writes a ready-to-use ~/.codex/config.toml. When you run the command, the generator orchestrates three key operations defined in cli/src/tools.ts.

Model Selection Logic

The generator selects the appropriate model by calling primaryModel() in cli/src/tools.ts (lines 17-30). By default, it picks the primary model from the live catalog, though you can override this with the --model flag to specify a particular model ID.

Provider Table Construction

The generator creates a [model_providers.freellmapi] block in cli/src/tools.ts (lines 88-94) that configures Codex to use the FreeLLMAPI base URL. This table sets wire_api = "responses", binds the environment variable FREELLMAPI_API_KEY as the credential via env_key, and disables OpenAI-specific authentication with requires_openai_auth = false.

Configure Codex CLI with Default Profile

To set up Codex CLI with FreeLLMAPI using the default profile, run the setup generator and export your unified API key:

# Install FreeLLMAPI if you haven't already

curl -fsSL https://freellmapi.co/install.sh | bash

# Generate the default Codex configuration

npx freellmapi setup-codex

The codex() function in cli/src/tools.ts (lines 84-134) writes the configuration directly to ~/.codex/config.toml. The resulting file contains:

# freellmapi:start

model = "auto"
model_provider = "freellmapi"
model_context_window = 128000
model_auto_compact_token_limit = 115200
tool_output_token_limit = 20000

[model_providers.freellmapi]
name = "FreeLLMAPI"
base_url = "http://localhost:3001/v1"
wire_api = "responses"
env_key = "FREELLMAPI_API_KEY"
requires_openai_auth = false

# freellmapi:end

Export your unified API key before invoking Codex. The generator explicitly does not store the key in the TOML file for security reasons.

export FREELLMAPI_API_KEY=your-unified-key
codex

Configure Codex CLI with Named Profiles

For users who need separate configurations (e.g., different models for work and personal projects), the generator supports named profiles via the --profile flag.

npx freellmapi setup-codex --profile work

When using a named profile, the generator modifies the TOML structure as implemented in cli/src/tools.ts (lines 128-133). The file contains a base provider table plus a [profiles.<NAME>] section that overrides only model-specific fields:

# freellmapi:start

[model_providers.freellmapi]
name = "FreeLLMAPI"
base_url = "http://localhost:3001/v1"
wire_api = "responses"
env_key = "FREELLMAPI_API_KEY"
requires_openai_auth = false

[profiles.work]
model = "auto"
model_provider = "freellmapi"

# freellmapi:end

Activate the profile when running Codex:

export FREELLMAPI_API_KEY=your-unified-key
codex --profile work

Launch Codex Without Persistent Credentials

If you prefer to avoid writing any configuration file, use the launch-codex command. This command, implemented in cli/src/index.ts (lines 249-254), starts Codex as a child process with the API key injected via the environment.

npx freellmapi launch-codex

This approach keeps the FREELLMAPI_API_KEY completely out of persistent storage while still routing all requests through FreeLLMAPI's unified endpoint at http://localhost:3001/v1.

Summary

• Use npx freellmapi setup-codex to generate a default profile configuration at ~/.codex/config.toml that points to http://localhost:3001/v1.
• The configuration binds to the responses wire API and references FREELLMAPI_API_KEY as an environment variable, never storing credentials in the TOML file.
• Named profiles are created with --profile <name> and generate isolated [profiles.<name>] tables while sharing the base provider configuration.
• Run launch-codex to start Codex without writing any configuration file, achieving zero-persistence credential management.
• All configuration logic resides in cli/src/tools.ts, specifically the codex() function (lines 84-134) and primaryModel() helper (lines 17-30).

Frequently Asked Questions

Where is the Codex configuration file stored?

FreeLLMAPI writes the configuration to ~/.codex/config.toml in your home directory. The generator creates this file automatically when you run setup-codex, and it places FreeLLMAPI configuration blocks between # freellmapi:start and # freellmapi:end comments to allow safe updates without overwriting other provider settings.

Do I need to edit the TOML file manually?

No. The setup-codex generator handles all TOML editing automatically through the codex() function in cli/src/tools.ts (lines 84-134). The tool inserts the correct [model_providers.freellmapi] table, sets the base URL to http://localhost:3001/v1, and configures the responses wire API without requiring manual intervention.

Why doesn't the configuration file contain my API key?

FreeLLMAPI deliberately keeps credentials out of the configuration file for security. The TOML references FREELLMAPI_API_KEY via the env_key parameter, and the generator reminds you to export this variable before running Codex. For zero-persistence workflows, use launch-codex to inject the key into the child process environment without writing it to disk.

Can I use different models for different projects?

Yes. Use the --profile flag when running setup-codex to create named profiles. Each profile generates a [profiles.<name>] table that overrides model settings while sharing the base FreeLLMAPI provider configuration. Switch between profiles using codex --profile <name>, as noted in the generator output in cli/src/tools.ts (lines 128-133).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}