# Codex CLI (/docs/develop/developer-tools/codex)



`Codex CLI` connects to BullSequana AI through the OpenAI **Responses** API on the `BSQAI API`. Codex runs its tools on your machine; the platform serves the model turns with a model your organization lets you use.

## What to use [#what-to-use]

* API type: OpenAI Responses API (`wire_api = "responses"`)
* base URL: `https://api.<platform-domain>/v1`
* token: `sk-bsq-...` API key, read from an environment variable

Do not configure Codex against an internal model endpoint, such as KServe's.

## 1. Install Codex CLI [#1-install-codex-cli]

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

## 2. Get a BSQAI API key [#2-get-a-bsqai-api-key]

Create one under **API Keys** in the Portal's account menu. The full secret is shown only once.

Give the key `chat.message.create` to generate answers, and `tenant.read` to list models in step 4. If you belong to a group in the tenant, also choose the **Team** the key's usage counts for. It cannot be changed later, and that team's monthly BCU cap applies to the key. See [Create and use an API key](/docs/develop/use-local-models-via-api#option-2-create-and-use-an-api-key).

Export the key in the shell that runs Codex:

```bash
export BSQ_API_KEY="sk-bsq-v1-..."
```

## 3. Configure the provider [#3-configure-the-provider]

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

```toml
model = "<model-name-from-/v1/models>"
model_provider = "bsqai"
model_context_window = <context-window>

[model_providers.bsqai]
name = "BullSequana AI"
base_url = "https://api.<platform-domain>/v1"
env_key = "BSQ_API_KEY"
wire_api = "responses"
```

* `env_key` names the variable Codex reads the key from, so the key is never written into the file. Codex sends it as `Authorization: Bearer`.
* `wire_api = "responses"` makes Codex call `/v1/responses`.
* `model_context_window` tells Codex the model's context window, which Codex does not read from the BSQAI API. Codex uses it to compact a long session before it reaches the model's limit. Use the model's `context_length` from `/v1/models`, or the value the deployment was started with.

The Portal generates this file with the model id, the base URL and the model's context window already filled in. Open the model in **Studio → Available models**, go to **Use model**, and pick Codex CLI under **Use with a coding agent**. See [Studio — Use model](/docs/use/portal/ai-hub#use-model).

## 4. Check model availability [#4-check-model-availability]

The `model` value must be a name from the model list of your environment:

```bash
curl "https://api.<platform-domain>/v1/models" \
  -H "Authorization: Bearer $BSQ_API_KEY"
```

The list holds only the models you may use. Pick a model deployed with tool calling: Codex reads files and runs commands through tool calls, and a model without them can only answer. See [A coding agent needs tool calling](/docs/develop/developer-tools#a-coding-agent-needs-tool-calling).

## 5. Run Codex [#5-run-codex]

```bash
codex
```

Ask a short question that needs a tool, such as listing the files in the current directory, to check that the model calls tools.

## Troubleshooting [#troubleshooting]

| Symptom                                    | Cause and fix                                                                                                                                                                                                                        |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`                                      | `BSQ_API_KEY` is not exported in the shell that runs Codex, or the key was deleted.                                                                                                                                                  |
| `404` with `model_not_found`               | The model name is wrong, or no allow rule lets you use the model. Check the name against `/v1/models`, or ask for **Can use** on the model.                                                                                          |
| `400` with `reasoning_effort_unsupported`  | The model rules out the reasoning effort Codex sent. Set `model_reasoning_effort` in `config.toml` to a value the model accepts.                                                                                                     |
| `429` with `usage_cap_reached`             | Your monthly BCU cap, or the cap of the key's team, is reached. Waiting does not help; a tenant administrator can raise it. See [What a refused call looks like](/docs/administration/usage-budgets#what-a-refused-call-looks-like). |
| The model answers but never runs a command | The model was deployed without tool calling. Use another model, or redeploy it with tool calling enabled.                                                                                                                            |

## Related pages [#related-pages]

* [Developer tools](/docs/develop/developer-tools)
* [Use local models via API](/docs/develop/use-local-models-via-api)
* [API Reference](/docs/reference)
