Codex CLI setup

Use Sage Router as the Codex model provider.

Point Codex at the hosted Sage Router API or a local/Tailnet router on port 8790, then run the stable sage-router/frontier profile.

Create hosted API key API reference Read quickstart Troubleshoot API errors Browse models Check status

Hosted Codex setup requires a generated sk_sage_* customer key. Local and Tailnet setup requires your own authorized provider credentials on the router host.

Hosted

Use the public edge

Use https://api.sagerouter.dev/v1/ with a generated account key when you want billing, quotas, and hosted reliability checks.

Local

Use port 8790

Use http://127.0.0.1:8790/v1/ when Codex and Sage Router run on the same workstation or Docker host.

Tailnet

Use a private host

Use http://<tailnet-host>:8790/v1/ for a private Sage Router installation reachable through your Tailnet.

Hosted profile

Append the hosted provider and profile.

Start here if you want one hosted sk_sage_* key for Codex. Copying this snippet is tracked as setup intent, without storing prompts or API keys.

Hosted Codex

export OPENAI_API_KEY=sk_sage_your_key_here
mkdir -p ~/.codex
cat >> ~/.codex/config.toml <<'TOML'
[model_providers.sage-router-hosted]
name = "Sage Router Hosted"
base_url = "https://api.sagerouter.dev/v1/"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.sage-router-frontier]
model_provider = "sage-router-hosted"
model = "sage-router/frontier"
TOML

codex --profile sage-router-frontier

Local profile

Use the same route through port 8790.

Local Codex

export SAGE_ROUTER_API_KEY=local
cat >> ~/.codex/config.toml <<'TOML'
[model_providers.sage-router-local]
name = "Sage Router Local"
base_url = "http://127.0.0.1:8790/v1/"
env_key = "SAGE_ROUTER_API_KEY"
wire_api = "responses"

[profiles.sage-router-local-frontier]
model_provider = "sage-router-local"
model = "sage-router/frontier"
TOML

codex --profile sage-router-local-frontier

Tailnet profile

Point Codex at a private Sage Router host.

Tailnet Codex

cat >> ~/.codex/config.toml <<'TOML'
[model_providers.sage-router-tailnet]
name = "Sage Router Tailnet"
base_url = "http://<tailnet-host>:8790/v1/"
env_key = "SAGE_ROUTER_API_KEY"
wire_api = "responses"

[profiles.sage-router-tailnet-frontier]
model_provider = "sage-router-tailnet"
model = "sage-router/frontier"
TOML

codex --profile sage-router-tailnet-frontier

Verify

Test the model list before starting Codex.

Model-list probes

curl https://api.sagerouter.dev/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

curl http://127.0.0.1:8790/v1/models \
  -H "Authorization: Bearer $SAGE_ROUTER_API_KEY"

Status	Likely cause	Next action
401	The Codex environment variable is missing, revoked, or not the key expected by the selected provider.	Check `env_key`, regenerate a hosted `sk_sage_*` key, or set the local router token.
402	The hosted account plan, quota, or billing state blocks model traffic.	Finish checkout, choose a plan, or review usage on the account page.
429	The account or router is rate limited.	Reduce Codex concurrency, retry later, or upgrade the hosted plan limit.
503	No authorized healthy backend route is currently available.	Check public status, local provider credentials, router health, and fallback policy.

For response headers, safe curl probes, and no-secret support context, use the hosted API troubleshooting page.

Support boundary

Keep prompts and secrets out of support requests.

Do not paste prompts, provider credentials, OAuth tokens, generated API keys, private keys, session cookies, raw provider responses, or customer data into public support channels. Safe troubleshooting context is limited to account email, plan, timestamp, request id, HTTP status, safe error class, and non-secret key prefix.