Connect a model¶

Goal¶

Replace the offline echo route with a provider connection and explicit model profile while keeping the credential outside configuration. Under an isolating execution boundary, grant only the provider's exact network origin.

For a provider-specific copy/paste path, choose from Connect a model provider. This onboarding page retains the single end-to-end starting flow; the focused guides cover Codex/ChatGPT, the OpenAI API, OpenRouter, local servers, and other compatible endpoints separately.

Prerequisites¶

A completed five-minute quickstart.
A provider account and model identifier. API-backed providers also need an API credential; a Codex subscription uses a ChatGPT sign-in instead.
Permission to expose the provider endpoint. Under isolation, authorize its exact HTTPS origin in the Colossus sandbox.
For an endpoint issued by a private CA, a PEM CA certificate bundle.

Steps¶

1. Authenticate without placing a credential in YAML¶

For a Codex subscription, install the official Codex CLI and let it own the ChatGPT OAuth flow. Colossus forces Codex's supported file-backed credential store so the provider adapter can reuse and refresh that sign-in:

colossus codex login
colossus codex status

On a remote or headless machine, use colossus codex login --device-code. If Codex is not on PATH, place --codex-bin /absolute/path/to/codex before the login, status, or logout subcommand. These commands do not require a valid Colossus configuration. Codex stores the sign-in under $CODEX_HOME/auth.json, or ~/.codex/auth.json when CODEX_HOME is unset. When set, CODEX_HOME must be absolute. After the official CLI exits successfully, Colossus validates that login and status produced a credential that passes runtime validation before reporting completed: true; logout reports completion only after that credential is no longer usable. Colossus rejects an existing auth file that fails runtime safety validation before invoking the account command; a failing remaining file is an error, not a successful logout. See OpenAI's Codex authentication documentation for the underlying supported login modes and credential storage behavior.

For an API-key provider, use one process-scoped variable for the examples below. The prompt does not echo the secret, and the command itself contains no credential value.

macOS and LinuxWindows PowerShell

printf "Provider API key: "
IFS= read -rs COLOSSUS_PROVIDER_API_KEY
printf "\n"
export COLOSSUS_PROVIDER_API_KEY

$secret = Read-Host "Provider API key" -AsSecureString
$env:COLOSSUS_PROVIDER_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password

Use your platform's secure secret injection mechanism for persistent or unattended operation. The process environment necessarily contains the resolved value while Colossus runs; close the shell when finished. Do not paste a secret into the selected configuration.

2. Add a provider profile and route¶

Run colossus config effective and edit the reported resolution.configPath. After the quickstart this is normally $COLOSSUS_HOME/config.yaml; a repository-local .colossus/config.yaml is a complete higher-priority replacement, not an overlay.

If the provider uses a private CA, add the runtime-wide bundle once. Relative paths are resolved from the selected workspace:

network:
  caBundlePath: .colossus/certs/company-ca-bundle.pem

Publicly trusted endpoints can leave caBundlePath as null or omit the network block.

Codex/ChatGPT subscriptionOpenAI ResponsesOpenAI-compatible provider

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

baseUrl is intentionally omitted and cannot be overridden. The first origin is the subscription-backed Responses service; the second is used only when the Codex-managed access token enters its five-minute refresh window.

reasoningEffort is optional. Valid values are none, minimal, low, medium, high, xhigh, max, and ultra; the selected Codex model may support only a subset. Omit it to use that model's backend default.

providers:
  profiles:
    openai-provider:
      kind: open_ai_responses
      baseUrl: https://api.openai.com/v1
      credentialReference: env:COLOSSUS_PROVIDER_API_KEY
models:
  profiles:
    openai:
      providerProfile: openai-provider
      model: YOUR_MODEL_ID
      contextWindowTokens: 128000
      maxOutputTokens: 16000
      capabilities:
        toolCalls: true
        streaming: true
  roles:
    primary: openai

sandbox:
  networkDestinations:
    - https://api.openai.com

providers:
  profiles:
    openrouter-provider:
      kind: open_ai_compatible
      baseUrl: https://openrouter.ai/api/v1
      credentialReference: env:COLOSSUS_PROVIDER_API_KEY
models:
  profiles:
    openrouter:
      providerProfile: openrouter-provider
      model: openrouter/free
      contextWindowTokens: 128000
      maxOutputTokens: 16000
      capabilities:
        toolCalls: true
        streaming: true
  roles:
    primary: openrouter

sandbox:
  networkDestinations:
    - https://openrouter.ai

Merge the provider and model fragments into the generated file. The shown sandbox fragments are exact grants for an explicitly isolating boundary; their origin contains only scheme, host, and effective port, while the API path remains in baseUrl. Acknowledged full access needs no duplicate destination and adding one does not narrow ambient HTTP(S) authority. See Sandbox configuration before treating an origin list as confinement.

3. Inspect routing and readiness¶

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

The route command is network-free. provider doctor checks the provider connection and catalog. models doctor sends one bounded generation probe for the configured model; its response content is not printed. Substitute codex-provider and codex, or the matching OpenRouter names, when following those examples.

4. Send one bounded model turn¶

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

Expected result¶

The route diagnostic names the configured profile, the provider doctor reports it ready, and the model run returns connected.

Verification¶

Inspect the active route and recent redacted audit envelopes:

colossus -w . provider profiles
colossus -w . models profiles
colossus -w . audit show --limit 10

The credential value must not appear in configuration, output, or audit evidence.

Failure path¶

Credential unavailable: for Codex, run colossus codex status and sign in again; for an API provider, confirm that the referenced variable is present in the Colossus process environment.
Origin denied under isolation: add the exact provider origin, not its URL path.
Provider or model not found: verify kind, baseUrl, and model with the provider.
TLS or certificate failure: set network.caBundlePath to the PEM bundle that issued the endpoint certificate, then rerun provider doctor.
Request denied: inspect config effective; provider visibility, action policy, approval, and network grants are separate decisions.
Outcome unknown: inspect provider-side usage before retrying. Colossus does not silently repeat a request that may have reached the service.

Next step¶

Give the model a constrained workspace in First repository task.