> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Using BeatAPI in Codex CLI

> Add BeatAPI as a custom model provider in Codex CLI so the terminal coding agent runs on any model in your account.

# Using BeatAPI in Codex CLI

Codex CLI is a terminal coding agent that reads and writes files, runs commands, and works through a task end to end. It talks to a provider over the OpenAI Responses format, which BeatAPI serves at `POST /v1/responses` — so BeatAPI is added as a provider rather than proxied.

## Prerequisites

1. **Node.js installed** — the LTS release, v20 or newer.
2. **A BeatAPI API key** — create one in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys).

## Step 1: Install Codex CLI

#### npm

```bash
npm install -g @openai/codex
```

On macOS or Linux, prepend `sudo` if you hit a permission error.

#### Homebrew (macOS)

```bash
brew install codex
```

Confirm the install:

```bash
codex --version
```

## Step 2: Add BeatAPI as a provider

Codex CLI keeps provider configuration under `~/.codex/` (`C:\Users\<you>\.codex\` on Windows). If the directory does not exist, run `codex` once and press `Ctrl + C`; it is created for you.

### 2.1 The key

Create or edit `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
}
```

### 2.2 The provider

Create or edit `~/.codex/config.toml`:

```toml
# Default model
model = "gpt-5.6-sol"
# Default provider — must match the id in [model_providers.<id>] below
model_provider = "beatapi"

[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
requires_openai_auth = true
```

| Field                  | Value                                                                     |
| ---------------------- | ------------------------------------------------------------------------- |
| `model`                | Any model ID from the table below                                         |
| `model_provider`       | Must match the id used in `[model_providers.<id>]`                        |
| `name`                 | Display label; choose anything                                            |
| `base_url`             | `https://api.beatapi.io/v1` — with the `/v1` suffix and no trailing slash |
| `wire_api`             | `responses`. Current Codex releases removed the `chat` protocol           |
| `requires_openai_auth` | `true` makes Codex authenticate with the key from `auth.json`             |

> **Note**
>
> Provider settings only take effect in the **user-level** `~/.codex/config.toml`. Codex ignores `model_provider` and `model_providers` in a project-local `.codex/config.toml` and prints a warning at startup. The ids `openai`, `ollama`, and `lmstudio` are reserved, which is why the block above defines a new id instead of overriding one of them.

Restart Codex CLI after saving both files.

### Alternative: use an environment variable instead of auth.json

```toml
[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
env_key = "BEATAPI_API_KEY"
```

Then export `BEATAPI_API_KEY` in your shell profile. `auth.json` is no longer needed. This keeps the key out of a file that is easy to commit by accident.

## Step 3: Verify and start working

```bash
codex "Introduce yourself in one sentence"
```

A reply means it is wired up. A sign-in screen, a `401`, or a `403` means it is not — see the FAQ.

Run `codex` on its own for the interactive UI, then describe the task in plain language:

```
Create an Express.js server with a JSON health check endpoint
```

Codex analyses the project, writes code, and runs commands, asking before anything sensitive.

### Approval modes

| Mode        | Behaviour                                                     |
| ----------- | ------------------------------------------------------------- |
| Read Only   | Reads files; any write or command needs confirmation          |
| Auto        | Reads, writes, and runs commands inside the working directory |
| Full Access | No confirmation at all                                        |

Start with Auto. Change it any time with `/approvals`.

## Models

Switch with `/model` in the interactive UI, or change `model` in `config.toml` and restart.

| Model ID        | Choose it for                                                     |
| --------------- | ----------------------------------------------------------------- |
| `gpt-5.6-sol`   | The strongest coding tier — the default for Codex                 |
| `gpt-6-astra`   | The newest generation, with a higher tier above 272K input tokens |
| `gpt-5.6-terra` | Balanced capability and cost for routine work                     |
| `gpt-5.6-luna`  | The fast, inexpensive tier for high-volume steps                  |

Any text model on the account answers on `/v1/responses`, so the list is not limited to the ones above — see the [Text API](/text-api). Rates are on the [pricing page](https://beatapi.io/pricing).

> **Note**
>
> `gpt-6-astra` and the GPT-5.6 family bill a higher rate above 272K input tokens, and `grok-4.5`, `grok-4.6`, and `grok-4.7` above 200K. A long agentic session can cross that line without any signal in the terminal; check the current pricing page and usage records when budgeting.

## Common commands

| Command                       | Description                       |
| ----------------------------- | --------------------------------- |
| `codex`                       | Enter the interactive UI          |
| `codex "task"`                | Start with an initial instruction |
| `codex exec "task"`           | Non-interactive — run and exit    |
| `codex --model gpt-5.6-terra` | Start with a specific model       |
| `/model`                      | Switch model inside the UI        |
| `/approvals`                  | Change approval mode              |
| `Ctrl + C`                    | Exit                              |

## FAQ

### A sign-in screen appears on launch

The configuration is not being read.

1. Both files must be in `~/.codex/` — not in the project directory.
2. `model_provider` must exactly match the id in `[model_providers.<id>]`.
3. `auth.json` must be valid JSON and `config.toml` valid TOML. Typographic quotes are the usual culprit; use straight quotes.

### 401 or 403

| Status | Meaning                                                                                            | What to do                                                                                        |
| ------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `401`  | `missing_api_key` or `invalid_api_key`: the key is missing, wrong, expired, disabled, or exhausted | Check the key in `auth.json` against [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys) |
| `403`  | `forbidden`: the key or account cannot use this model, for example on free credit                  | Check account status and the requested model                                                      |

Also confirm `base_url` is `https://api.beatapi.io/v1` and not a vendor's own address.

### `wire_api = "chat"` is rejected

Current Codex releases removed the Chat Completions protocol. Set `wire_api = "responses"` and restart. BeatAPI serves the Responses format, so nothing else changes.

### 404 on every request

Almost always the base URL. It must end in `/v1`, with no trailing slash and no further path.

### 402 insufficient_credits

Insufficient balance: the balance is zero or below the price of the request. Top up from the dashboard.

### 429 rate_limit_exceeded

The key exceeded its request rate. Honour the `Retry-After` header. The per-minute allowance rises with lifetime top-ups and is shown on the dashboard.

### Tool calls fail

Confirm `wire_api = "responses"`. If a specific model still misbehaves under Codex's tool protocol, try `gpt-5.6-sol`, which is the most heavily exercised pairing.

## Support

Open a support ticket from the [dashboard](https://beatapi.io/dashboard) and include the `request_id` from the failing response.