---
title: "Integrate with Codex"
description: "Point Codex CLI, the ChatGPT desktop app and the VS Code extension at AI Runtime with one API key and one model name."
---

> Documentation Index
> Fetch the complete documentation index at: https://help.airuntime.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate with Codex

## What you get

Codex is an AI coding assistant from OpenAI. It talks to models over the Responses API, which
`https://api.airuntime.dev/v1` also exposes. All Codex clients — Codex CLI, the ChatGPT desktop app,
and the Codex IDE extension for VS Code — read the same configuration file, so configuring it once
makes AI Runtime available in all of them.

You call one name, `deepseek`. AI Runtime decides which reviewed upstream answers it with; vendor
model ids never appear in your configuration or your requests.

## 1. Configure AI Runtime as the model provider

You need a Workspace API Key. It is shown once when you issue it in the console, and it starts with
`rk_`. The Pool the key may call decides which model name you get; this page assumes a text Pool
whose model is `deepseek`.

### Option 1: Setup script (recommended)

Make sure Codex CLI or the ChatGPT desktop app has been launched at least once, so that
`~/.codex` exists. Then run, on macOS or Linux:

```bash
bash <(curl -fsSL https://help.airuntime.dev/codex-airuntime-setup.sh)
```

Pick `1` to point Codex at AI Runtime, or `9` to undo it. The script:

- backs up `~/.codex/config.toml` to `~/.codex/backup-airuntime/`, so the previous configuration can
  be restored at any time;
- writes the model catalog `~/.codex/model-catalogs/airuntime.json`, which declares the metadata
  Codex needs (context window, reasoning levels, tool call format) so it treats `deepseek` like a
  built-in model;
- adds a `[model_providers.airuntime]` section to `~/.codex/config.toml` and rewrites only the
  fields it needs. Your MCP servers, project trust levels and everything else are left alone;
- writes your API key into `~/.codex/config.toml` as `experimental_bearer_token` inside
  `[model_providers.airuntime]`, the same way DeepSeek's own setup script does it. Keep that file
  readable only by you (`chmod 600 ~/.codex/config.toml`);
- validates the generated files before writing them. If validation fails, nothing is modified.

Run it again at any time to rewrite the configuration, or pick `9` to restore the state from before
the installation. If you also keep `~/.codex/switch-model.sh`, `switch-model.sh airuntime` does the
same install, and `switch-model.sh restore-airuntime` does the same restore.

### Option 2: Edit the configuration files yourself

First write the model catalog to `~/.codex/model-catalogs/airuntime.json`. The file the setup
script writes is served at [/airuntime-models.json](https://help.airuntime.dev/airuntime-models.json); download it, or copy
its contents. The fields that matter most are `slug` (the name Codex sends, `deepseek`),
`apply_patch_tool_type` (`freeform`), `context_window` and `supported_reasoning_levels`.

Then add this to `~/.codex/config.toml`:

```toml
model = "deepseek"
model_provider = "airuntime"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/model-catalogs/airuntime.json"
web_search = "disabled"

[model_providers.airuntime]
name = "AI Runtime"
base_url = "https://api.airuntime.dev/v1"
wire_api = "responses"
experimental_bearer_token = "rk_..."
```

Replace `rk_...` with the API key from your AI Runtime dashboard, then keep the file readable only
by you:

```bash
chmod 600 ~/.codex/config.toml
```

This is the same shape DeepSeek's own Codex integration uses: one key, one provider block, no
separate credential store.

### config.toml field reference

| Field | Description |
| --- | --- |
| `model` | The default model. This is the name your Pool serves, not a vendor model id. |
| `model_provider` | The provider to use, matching the id of the `[model_providers.<id>]` section below. |
| `model_reasoning_effort` | How much the model thinks before answering. `low`, `high` and `max` are supported. |
| `web_search` | Built-in web search. Disabled for this model. |
| `model_catalog_json` | Path to the model catalog above, from which Codex reads model metadata. |
| `name` in `[model_providers.airuntime]` | Display name of the provider. |
| `base_url` in `[model_providers.airuntime]` | AI Runtime API origin, `https://api.airuntime.dev/v1`. |
| `wire_api` in `[model_providers.airuntime]` | The protocol used to talk to the model. `responses` means the Responses API. |
| `experimental_bearer_token` in `[model_providers.airuntime]` | Your AI Runtime API key. The setup script writes it here, as DeepSeek's own script does. |

## 2. Get started

All three clients read the same file, so there is no per-client configuration:

- **Codex CLI.** Enter a project directory and run `codex`. If the banner shows
  `model: deepseek`, the configuration is in effect.
- **ChatGPT desktop app.** A model picker showing "Custom" or the model name means the
  configuration is in effect; which of the two appears depends on your version.
- **Codex IDE extension for VS Code.** It shares the configuration with Codex CLI; install it and
  start using it.

## Sessions after switching providers

Codex groups session history by how you authenticated: sessions from a ChatGPT subscription and
sessions from a third-party API key are kept apart, and it shows the group matching your current
configuration. Nothing is deleted. Point the configuration back and the earlier sessions reappear,
while the AI Runtime sessions become hidden in turn. Restart the client after switching.

Source: https://help.airuntime.dev/codex/integrate-with-codex/index.mdx
