> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runbridge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Codex with RunBridge AI

> Configure a custom Codex provider with the Responses API and your RunBridge AI key.

Connect [Codex](https://developers.openai.com/codex/quickstart) to RunBridge AI through its custom model provider configuration. Codex sends requests to the [Responses API](/api/text/responses).

## Prerequisites

* Install the app or CLI from the [official Codex quickstart](https://developers.openai.com/codex/quickstart).
* Create an active API key in the [RunBridge AI dashboard](https://runbridge.ai/console/token).
* Choose an exact [model ID](/overview/models) that supports **Responses, streaming, and tool calling**. Replace `your-model-id` below; a Chat Completions-only model is not sufficient.

For the CLI, the official npm installation is:

```bash theme={null}
npm install -g @openai/codex
codex --version
```

## Configure the provider

Edit your user configuration at `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\config.toml`). If `CODEX_HOME` is already set, use `config.toml` in that directory instead. Merge the following with existing settings; keep top-level `model` and `model_provider` before any TOML table headers.

```toml theme={null}
model = "your-model-id"
model_provider = "runbridge"

[model_providers.runbridge]
name = "RunBridge AI"
base_url = "https://api.runbridge.ai/v1"
wire_api = "responses"
env_key = "RUNBRIDGE_API_KEY"
```

`runbridge` is the custom provider ID defined here. The base URL ends in `/v1`; Codex appends `/responses`.

## Supply the API key

Use an environment variable when you launch Codex from a terminal. Enter the key at the hidden prompt rather than including it in a command saved to shell history.

<Tabs>
  <Tab title="Bash / Zsh">
    ```bash theme={null}
    printf 'RunBridge AI API key: '
    read -rs RUNBRIDGE_API_KEY
    printf '\n'
    export RUNBRIDGE_API_KEY
    codex
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    $secureKey = Read-Host "RunBridge AI API key" -AsSecureString
    $env:RUNBRIDGE_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password
    codex
    ```
  </Tab>
</Tabs>

### Desktop app authentication

An app opened from the dock or Start menu may not inherit your terminal environment. Use Codex's [command-backed authentication](https://developers.openai.com/codex/config-advanced#custom-model-providers) if the app cannot read `RUNBRIDGE_API_KEY`.

On macOS or Linux, create `~/.codex/runbridge_key` outside any repository, restrict it to your user, and enter your key manually in a local editor. For a new file:

```bash theme={null}
mkdir -p "$HOME/.codex"
touch "$HOME/.codex/runbridge_key"
chmod 600 "$HOME/.codex/runbridge_key"
```

Save only the key, on one line. Remove `env_key` from the provider above and add:

```toml theme={null}
[model_providers.runbridge.auth]
command = "/bin/sh"
args = ["-c", "cat \"$HOME/.codex/runbridge_key\""]
```

On Windows, store the key in `%USERPROFILE%\.codex\runbridge_key`, restrict file access to your Windows user, and use this block instead:

```toml theme={null}
[model_providers.runbridge.auth]
command = "powershell.exe"
args = ["-NoProfile", "-Command", "$p=Join-Path $HOME '.codex/runbridge_key'; (Get-Content -Raw $p).Trim()"]
```

These examples use the default key-file location; adjust the command if you store it elsewhere. The command must return only the token on stdout. Do not run it in a shared terminal or paste its output into logs. Restart the app after changing configuration.

<Note>
  Use one authentication method per provider. Do not combine an `auth` block with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`. Keep your existing ChatGPT login; custom provider authentication does not require replacing `auth.json`.
</Note>

## Verify the connection

Start a new local Codex session in a test project. Confirm the selected model and provider, then ask: **Reply with “RunBridge connected” without reading or changing files.** Check that the request appears in your RunBridge AI usage records.

A text reply verifies a basic request. Before using the agent on a real task, verify tool calling in a disposable project with a model that supports it.

## Troubleshooting

| Symptom | Check |
| - | - |
| Missing `RUNBRIDGE_API_KEY` | Export the variable in the process that starts Codex, or use command-backed authentication for the app. |
| Empty-token or command error | Confirm the private key file exists, is nonempty, and is readable by the app's user. |
| 401 | Check the key's validity and access in the RunBridge AI dashboard. |
| 404 or unsupported endpoint | Keep `/v1` in `base_url`, omit `/responses` there, and choose a Responses-compatible model. |
| Tool or stream errors | Check the model's streaming and tool-calling support; a successful plain text response alone does not establish agent compatibility. |

See [Codex advanced configuration](https://developers.openai.com/codex/config-advanced) and [authentication](https://developers.openai.com/codex/auth) for the current provider contract.

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "headline": "Use Codex with RunBridge AI",
    "description": "Configure a custom Codex provider with the Responses API and your RunBridge AI key.",
    "url": "https://runbridge.mintlify.site/integrations/codex",
    "inLanguage": "en",
    "publisher": {
      "@type": "Organization",
      "name": "RunBridge AI"
    }
    }
    `}
</script>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.