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

# Codex CLI on Sideren.

> Codex talks the OpenAI Responses protocol. One provider block in config.toml points it at the gateway; the key lives in that block so Desktop and new terminals work without an env var.

## One command

```sh theme={null}
npx sideren setup --tool codex --key sdn_your_key
```

The setup helper writes the provider block below into `~/.codex/config.toml` (with a backup), puts
the key in `experimental_bearer_token`, and writes a model catalog so Codex knows the
Sideren model ids. See [setup helper](/setup).

## By hand

Add a provider to `~/.codex/config.toml`. Three details matter: the base URL **includes**
`/v1`, the wire protocol is `responses`, and the top-level keys go **above** the
`[model_providers.sideren]` header — TOML scopes every key after a table header into that
table, so `model` written below it silently becomes `model_providers.sideren.model`.

```toml title="~/.codex/config.toml" theme={null}
model = "auto"
model_provider = "sideren"
model_catalog_json = "/home/you/.codex/model-catalogs/sideren.json"

[model_providers.sideren]
name = "Sideren"
base_url = "https://api.sideren.io/v1"
experimental_bearer_token = "sdn_your_key"
requires_openai_auth = false
wire_api = "responses"
```

Do **not** set `env_key = "SIDEREN_API_KEY"`. Codex checks that variable first and errors
when it is missing — including in Codex Desktop, which does not inherit User environment
variables. `npx sideren setup` writes `experimental_bearer_token` instead.

The catalog file is required too. Without it Codex prints `Model metadata for
auto not found` and falls back to generic limits. Setup writes
`~/.codex/model-catalogs/sideren.json`, with one entry per Sideren model (its own context
window, compaction limit and reasoning levels), and points `model_catalog_json` at it.

If your config already declares `model_providers` as an **inline** table, add the provider
inside it instead — TOML cannot extend an inline table with a dotted key:

```toml title="~/.codex/config.toml" theme={null}
model_providers = { sideren = { name = "Sideren", base_url = "https://api.sideren.io/v1", experimental_bearer_token = "sdn_your_key", requires_openai_auth = false, wire_api = "responses" } }
```

`model` accepts any [catalog id](/models) — a coding flagship like `@sdn/glm-5` is a strong
daily driver for heavy sessions.

## Troubleshooting

* **`cannot extend value of type inline table with a dotted key`?** Your config already has
  `model_providers = { … }` on one line, and a `[model_providers.sideren]` header below it is
  invalid TOML. Merge the provider into the inline table (see above) — `npx sideren setup`
  does this for you.
* **Codex still calls its old model?** `model` is a top-level key and Codex only serves one:
  if it still names an OpenAI-only slug that isn't in the [catalog](/models), that request
  goes to Sideren under a model id the gateway doesn't serve. Setup takes the key over and
  leaves the old value as a `# sideren:was …` comment; `npx sideren unset` puts it back.
* **A profile in play?** A profile file (`~/.codex/<name>.config.toml`, used with
  `codex --profile <name>`) is layered over `config.toml`, so its own `model` /
  `model_provider` beat the top-level ones. Set `model_provider = "sideren"` inside the
  profile you launch with. Codex 0.134 and later no longer read `[profiles.…]` tables or a
  top-level `profile = …` key.
* **Empty responses?** Reasoning models spend hidden reasoning tokens from
  `max_output_tokens` — a very low budget can be consumed before any text is emitted.
  Raise it (4,000+ is a safe floor) or pick a non-reasoning model.
* **`Missing environment variable: SIDEREN_API_KEY`?** An older version of the setup helper set
  `env_key` and expected the variable in the process environment. Re-run
  `npx sideren setup --tool codex --key sdn_your_key` — the key goes in the
  provider table, so Desktop and already-open terminals work.
* **`Model metadata for … not found`?** Codex only ships OpenAI slugs. Setup writes
  `model_catalog_json` pointing at `~/.codex/model-catalogs/sideren.json`. Re-run setup
  if that file is missing.
* **401 unauthorized?** The provider table's `experimental_bearer_token` is empty or stale —
  re-run setup with `--key`.
* **404s?** Unlike Claude Code, the Codex base URL **must** end in `/v1`.
* **Protocol errors?** Keep `wire_api = "responses"` — the gateway serves the
  [Responses](/api/responses) dialect on `/v1/responses` for exactly this client.

<Note>
  Switching models mid-project is a one-line change to `model` — the provider block stays
  put.
</Note>


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