Agents

Codex

Local CLI; app and IDE extension use their active user configuration.

Setting up with an AI assistant? Copy the setup prompt or open this guide as Markdown.

Setup prompt

Read https://zrelay.net/docs/ai.md and https://zrelay.net/docs/md/agents/coding-agents/codex.md first.

Configure Codex CLI for Zrelay on this machine. Detect OS, shell, version and CODEX_HOME without exposing secrets. Read https://developers.openai.com/codex/config-advanced/ and https://keys.zrelay.net/api/catalog. For Codex 0.134.0 or later create or merge zrelay.config.toml in CODEX_HOME (default ~/.codex), preserving config.toml, login and unrelated settings. Use model="gpt-6.1-sol", model_provider="zrelay", web_search="disabled"; provider zrelay with name="Zrelay", base_url="https://api.zrelay.net/v1", env_key="ZRELAY_API_KEY", wire_api="responses", requires_openai_auth=false and supports_websockets=false. Confirm my selected pool enables this exact Responses route and respect its limits. Back up existing files privately. Never request, read out, print, log or save my real key; provide local hidden-entry instructions. Validate configuration offline and provide codex --profile zrelay without sending a prompt. Ask before installing/upgrading or paid inference. For app/extension adapt the active user config and process environment, explaining the shared default change. Report checks separately from untested runtime streaming and tools.

Manual setup

1. Check codex --version. This profile recipe requires Codex 0.134.0 or later. Follow the official CLI installation page if it is missing. Respect a custom CODEX_HOME. Create or merge ~/.codex/zrelay.config.toml (Windows: %USERPROFILE%\.codex\zrelay.config.toml); keep root keys before tables and preserve unrelated settings.

2. Use the TOML below. Current profiles are separate files: legacy [profiles.zrelay] tables no longer select this profile. Project .codex/config.toml cannot define the provider. Do not alter auth.json, the saved login or OPENAI_API_KEY.

3. Enter the key privately using the command for your shell, then run codex --profile zrelay from your project. Inspect /status without sending a prompt. Environment variables last for that session; graphical apps need the variable in their own process.

4. For the local app or IDE extension, back up and merge the same provider and root settings into the active user config.toml instead. In the extension use Codex Settings > Open config.toml. This changes the default for local clients sharing that file; a CLI profile is not automatically selected by the app. Restart with the secret available; WSL uses Linux paths. ChatGPT web does not read local files.

Configuration and commands

toml

model = "gpt-6.1-sol"
model_provider = "zrelay"
web_search = "disabled"

[model_providers.zrelay]
name = "Zrelay"
base_url = "https://api.zrelay.net/v1"
env_key = "ZRELAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

bash

read -rsp 'Zrelay API key: ' ZRELAY_API_KEY; printf '\n'
export ZRELAY_API_KEY

zsh

read -rs 'ZRELAY_API_KEY?Zrelay API key: '; printf '\n'
export ZRELAY_API_KEY

powershell

$zrSecret = Read-Host 'Zrelay API key' -AsSecureString
$env:ZRELAY_API_KEY = [System.Net.NetworkCredential]::new('', $zrSecret).Password
Remove-Variable zrSecret

Alternative: ask an AI assistant

Copy this complete prompt into your coding assistant. It describes configuration work; installation and paid tests need your authorization.

Setup prompt

Configure Codex CLI for Zrelay on this machine. Detect OS, shell, version and CODEX_HOME without exposing secrets. Read https://developers.openai.com/codex/config-advanced/ and https://keys.zrelay.net/api/catalog. For Codex 0.134.0 or later create or merge zrelay.config.toml in CODEX_HOME (default ~/.codex), preserving config.toml, login and unrelated settings. Use model="gpt-6.1-sol", model_provider="zrelay", web_search="disabled"; provider zrelay with name="Zrelay", base_url="https://api.zrelay.net/v1", env_key="ZRELAY_API_KEY", wire_api="responses", requires_openai_auth=false and supports_websockets=false. Confirm my selected pool enables this exact Responses route and respect its limits. Back up existing files privately. Never request, read out, print, log or save my real key; provide local hidden-entry instructions. Validate configuration offline and provide codex --profile zrelay without sending a prompt. Ask before installing/upgrading or paid inference. For app/extension adapt the active user config and process environment, explaining the shared default change. Report checks separately from untested runtime streaming and tools.

Limits and verification

The example gpt-6.1-sol has GPT Flex/Prime Responses routes. Context metadata must respect 128000 input and 4096 output; do not use the Zrelay catalog as Codex model_catalog_url. Hosted search, remote compaction, WebSockets and complete tool loops are not established by this recipe.

These recipes were reviewed against documentation and public catalog data. No client installation, authenticated request, paid inference, streaming or tool loop was executed. Validate configuration first; a later short text test does not establish complete agent compatibility.

Recheck the live catalog and your key’s provider/pool. The reviewed examples have 128000 input and 4096 output maxima unless a client limitation above prevents controlling the request. Never print, log or commit credentials.