Documentation
Documentation menu

Codex

Connect Codex CLI to Etage: prepare your key, write the configuration and start on Windows or macOS/Linux.

On this page

Before you start

You need Codex CLI installed, an Etage API key and available credits. Create a key and allow a model compatible with Responses. This guide configures the terminal client, not Codex Desktop.

1. Open the configuration folder

Codex must already be installed. Fully quit it before editing. If configuration exists, make a backup first. The examples below are for a new setup; in an existing file merge only the required Etage fields without removing other connections, security settings or sign-in data.

Windows: press Win + R and open %USERPROFILE%\.codex. If the folder is missing, create it with the PowerShell command below (not CMD), then edit the file in Notepad. On macOS open Terminal; on Linux use your terminal. The second tab creates the folder and opens the file in nano; another text editor also works. Examples use the standard home directory; if you changed the client configuration location, use your own path.

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

2. Write config.toml

Paste the TOML below. Etage uses Responses with the base URL https://api.etage.one/v1. The model and review_model values select gpt-6.1-sol; to switch, update both to an allowed Model ID compatible with Responses. This minimal example needs only config.toml and auth.json, not a separate model catalogue. Do not add /v1 twice.

In an existing TOML add or update only the required fields and model_providers.etage table. Do not duplicate tables. Preserve your approval, sandbox and network restrictions; connecting does not require weakening them. If you used another authentication method, back it up and check conflicting settings first.

TOML
model = "gpt-6.1-sol"
review_model = "gpt-6.1-sol"
model_provider = "etage"

[model_providers.etage]
name = "Etage"
base_url = "https://api.etage.one/v1"
wire_api = "responses"
requires_openai_auth = true

3. Create auth.json in the same folder

Open the second file in the same .codex folder, not in your project folder. On Windows use PowerShell and Notepad; on macOS/Linux open it in nano. If auth.json already exists, back it up first: previous sign-in data must not be lost when switching to an API key.

PowerShell
notepad "$HOME\.codex\auth.json"

4. Write your key in auth.json

For a new setup paste the JSON below and replace YOUR_API_KEY with your Etage key. Do not put the key in config.toml. auth.json is a regular local secret-containing file, not encrypted storage: never send it to chat, support or a repository. Check that old environment variables or credential helpers do not override the connection.

JSON
{
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

5. Save the files

Save as plain UTF-8 text. In Notepad choose All files, press Ctrl + S and check that .txt was not added to the filename. In nano: Ctrl + O → Enter → Ctrl + X. On macOS/Linux restrict access to key-containing files with the command below; do not publish them or their backups.

Fully quit Codex before starting again: an existing session may keep old settings. Preserve your approval rules, sandbox and network restrictions.

Bash
chmod 600 "$HOME/.codex/auth.json"

6. Start Codex

Open a terminal in your project folder and run the command. In the client check the selected model and Etage connection.

Bash
codex

Verify the connection

Test with a short request without secrets; it spends credits. After a response, check Usage for a retained record. A missing record does not establish zero spending. Configuration does not guarantee compatibility with every model.

Troubleshooting

Never publish auth.json or disable sandbox or approvals to fix a connection. Check the following settings.

  • 401/403: check the auth.json key, expiry, model access and credits.
  • Model not found: check the exact Model ID in model and review_model and Responses support.
  • Configuration error: check TOML/JSON, UTF-8, duplicate tables and unexpected .txt extensions.
  • Stale settings: fully restart Codex; check model_provider, the .codex path and conflicting authentication variables.