# Manual configuration for Codex

> Connect Codex to ScaleMax through the Responses API without npx or a project-level secret.

> **This page is for Codex, not Claude Code.** Codex uses an OpenAI-compatible Responses provider. For Claude Code's Anthropic Messages settings, use [Manual configuration for Claude Code](https://docs.scalemax.pro/docs/manual-configuration/claude-code).

## Choose the URL that belongs to the key

- **API-credit key:** `https://api.scalemax.pro/v1`
- **OpenAI token-pack key:** `https://api.scalemax.pro/token/v1`

The key types are intentionally isolated. Do not use an API-credit key on the token URL or a token-pack key on the credit URL. Claude token-pack keys cannot use the Codex model catalog.

## Configure the Responses provider

Create `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\config.toml`), or merge these fields into the user config while preserving unrelated settings. If you bought an OpenAI token pack, change only `base_url` to `https://api.scalemax.pro/token/v1`. This opens the file in an editor, creating it if needed:

**macOS / Linux**

```bash
mkdir -p ~/.codex && ${EDITOR:-nano} ~/.codex/config.toml
```

**Windows PowerShell**

```powershell
New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
notepad "$HOME\.codex\config.toml"
```

config.toml:

```toml
model = "gpt-5.6-terra"
model_provider = "scalemax"

[model_providers.scalemax]
name = "ScaleMax"
base_url = "https://api.scalemax.pro/v1"
wire_api = "responses"
requires_openai_auth = true
```

`wire_api = "responses"` is required. Do not set this provider to Anthropic Messages, and do not put the API key in `config.toml` or a repository-level `.codex/config.toml`.

## Log in without exposing the key

Codex CLI and the Codex IDE extension share the same user configuration and authentication. This prompt does not echo the key or place it in shell history:

**macOS / Linux**

```bash
printf "ScaleMax API key: "
IFS= read -r -s SCALEMAX_API_KEY
printf "\n"
printf "%s" "$SCALEMAX_API_KEY" | codex login --with-api-key
unset SCALEMAX_API_KEY
```

**Windows PowerShell**

```powershell
$secret = Read-Host "ScaleMax API key" -AsSecureString
[System.Net.NetworkCredential]::new("", $secret).Password | codex login --with-api-key
Remove-Variable secret
```

If PowerShell says running scripts is disabled, use `codex.cmd` in place of `codex`.

Codex stores the credential in its configured authentication store. To replace it, run the login command again; to remove it, run `codex logout`.

## Available Codex models

- `gpt-6.1-sol` — GPT-6.1 Sol
- `gpt-6-sol` — GPT-6 Sol
- `gpt-6-luna` — GPT-6 Luna
- `gpt-6-astra` — GPT-6 Astra
- `gpt-5.6-terra` — GPT-5.6 Terra
- `gpt-5.6-sol` — GPT-5.6 Sol
- `gpt-5.6-luna` — GPT-5.6 Luna

Use an exact ID. `gpt-5.6-terra` is the default in the config above; the GPT-6 models work the same way. `gpt-5.6-luna` is useful for a low-cost connectivity check. Your key's own list is always at `GET /v1/models`.

## Verify with a tiny request

For a direct one-token API check, set the key only in the current terminal, run this request, and then clear it (`unset SCALEMAX_API_KEY`, or in PowerShell `Remove-Item Env:SCALEMAX_API_KEY`):

**macOS / Linux**

```bash
export SCALEMAX_API_KEY="YOUR_SCALEMAX_KEY"

curl -sS "https://api.scalemax.pro/v1/responses" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "K",
    "max_output_tokens": 1
  }'
```

**Windows PowerShell**

```powershell
$env:SCALEMAX_API_KEY = "YOUR_SCALEMAX_KEY"

@'
{
  "model": "gpt-5.6-luna",
  "input": "K",
  "max_output_tokens": 1
}
'@ | Set-Content -Path body.json

curl.exe -sS "https://api.scalemax.pro/v1/responses" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

A successful response has an `id` and an output item. Then verify that Codex itself reads the provider:

**macOS / Linux**

```bash
codex exec \
  --model gpt-5.6-luna \
  --sandbox read-only \
  --skip-git-repo-check \
  "Reply with the single uppercase letter K."
```

**Windows PowerShell**

```powershell
codex exec `
  --model gpt-5.6-luna `
  --sandbox read-only `
  --skip-git-repo-check `
  "Reply with the single uppercase letter K."
```

## Automatic configuration

Install the reusable CLI once, then run it directly—no `npx` is required:

**macOS / Linux**

```bash
npm install -g scalemax@latest
scalemax
```

**Windows PowerShell**

```powershell
npm.cmd install -g scalemax@latest
scalemax.cmd
```

Windows PowerShell blocks npm’s .ps1 launchers by default (“running scripts is disabled on this system”), so these commands use the .cmd launcher: npx.cmd, npm.cmd, scalemax.cmd. In Command Prompt you can leave out .cmd.

Select **Codex** and the key's detected billing mode. The CLI backs up the existing user config, writes the Responses provider, authenticates safely, and verifies the selected model. Run `scalemax doctor` afterward for a repeatable health check.

## Security boundary

> Keep authentication in the Codex user store. Project configuration can select a model but should never contain a ScaleMax key or redirect provider credentials for other users.