# How to Set Up Codex CLI with FreeLLMAPI: A Complete Configuration Guide > Effortlessly set up Codex CLI with FreeLLMAPI. This guide shows you how to generate a working Codex CLI config automatically, ensuring seamless integration and secure API key management. - Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi) - Tags: how-to-guide - Published: 2026-08-29 --- **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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts). ### Model Selection Logic The generator selects the appropriate model by calling `primaryModel()` in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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: ```bash # 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) (lines 84-134) writes the configuration directly to `~/.codex/config.toml`. The resulting file contains: ```toml # 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. ```bash 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. ```bash npx freellmapi setup-codex --profile work ``` When using a named profile, the generator modifies the TOML structure as implemented in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) (lines 128-133). The file contains a base provider table plus a `[profiles.]` section that overrides only model-specific fields: ```toml # 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: ```bash 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/index.ts) (lines 249-254), starts Codex as a child process with the API key injected via the environment. ```bash 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 ` and generate isolated `[profiles.]` 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.]` table that overrides model settings while sharing the base FreeLLMAPI provider configuration. Switch between profiles using `codex --profile `, as noted in the generator output in [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) (lines 128-133).