Skip to content

Connect a Codex or ChatGPT subscription

Goal

Route the primary Colossus model through an eligible ChatGPT/Codex subscription without creating or storing an OpenAI API key.

Prerequisites

  • A ChatGPT plan that includes Codex access.
  • The official Codex CLI installed and available on PATH.
  • A schema version 2 configuration generated by colossus config init.
  • The exact model identifier and limits supported by your plan.

A ChatGPT subscription is not OpenAI API credit. This path uses a ChatGPT sign-in and kind: open_ai_codex; use OpenAI API for API-key authentication and separate API billing.

Steps

1. Sign in through Codex

colossus codex login
colossus codex status

For a headless machine, use colossus codex login --device-code. If the executable is not on PATH, put --codex-bin /absolute/path/to/codex before login, status, or logout. Colossus delegates the account flow to the official CLI and reuses its file-backed credential; the token never enters YAML. If CODEX_HOME is set, it must be absolute. A successful colossus codex status means both that the official CLI completed and that Colossus can safely load the resulting file-backed credential. Colossus rejects an existing auth file that fails runtime safety validation before starting an official CLI account operation.

Use colossus codex logout when you intentionally want to remove the current sign-in. It reports completion only after the credential is unavailable; an unsafe remaining store fails verification.

2. Configure the subscription route

Run colossus -w . config effective, edit the reported resolution.configPath, and keep its required storage block and any intended custom settings. Replace its schemaVersion, providers, and models values with this validated overlay, then replace YOUR_CODEX_MODEL_ID and the limits with values for the selected catalog entry.

schemaVersion: 2
providers:
  profiles:
    codex-provider:
      kind: open_ai_codex
      credentialReference: codex:default
models:
  profiles:
    codex:
      providerProfile: codex-provider
      model: YOUR_CODEX_MODEL_ID
      contextWindowTokens: 128000
      maxOutputTokens: 16000
      reasoningEffort: high
      capabilities:
        toolCalls: true
        streaming: true
  roles:
    primary: codex
sandbox:
  networkDestinations:
    - https://chatgpt.com
    - https://auth.openai.com

Do not add baseUrl. The adapter owns its supported backend URL and sends the Codex-managed credential only to fixed service and refresh endpoints. Both origins are required under an isolating boundary so an expiring token can refresh. Acknowledged full access supplies ambient authority for both fixed endpoints without duplicate grants.

reasoningEffort is optional. Choose only a level supported by the selected model, or omit it to use the backend default; Colossus does not assume every model supports every level.

3. Inspect routing and readiness

colossus -w . models route primary
colossus -w . provider doctor codex-provider
colossus -w . provider models codex-provider
colossus -w . models doctor codex

4. Send one bounded model turn

colossus -w . run \
  "Reply with exactly: connected"

Expected result

The role resolves to codex, both diagnostics succeed, and the bounded run returns connected through the subscription-backed provider.

Verification

Run colossus codex status again and inspect colossus -w . config show. The configuration must contain only credentialReference: codex:default, never a token or ChatGPT account identifier.

Failure path

  • The login is missing or expired: run colossus codex status, then colossus codex login again. Confirm the Codex auth file is a regular, owner-private file.
  • The backend says it requires a newer Codex version: run colossus --version and upgrade Colossus to a release with a newer reviewed Codex wire contract, then rerun provider doctor. Updating only the login CLI does not change the protocol version pinned in the Colossus adapter.
  • The account flow itself fails: run codex --version, update the official Codex CLI, and retry colossus codex login or the device-code flow.
  • The model or reasoning level is rejected: run provider models codex-provider, copy an exact visible model ID, and omit or correct reasoningEffort before rerunning models doctor codex.
  • Refresh cannot reach the auth service under isolation: retain both exact sandbox destinations and rerun provider doctor codex-provider.

Next step

Review exact subscription-provider rules in Providers and models, apply deployment guidance from Providers and routing, or continue with First repository task.