Skip to content

Connect OpenRouter

Goal

Route the primary Colossus model through OpenRouter using the existing open_ai_compatible Chat Completions adapter.

Prerequisites

  • An OpenRouter account and API key available to the Colossus process.
  • A schema version 2 configuration generated by colossus config init.
  • The exact OpenRouter model identifier and that model's limits and capabilities.

OpenRouter is a worked compatible-provider configuration, not a separate Colossus adapter.

Steps

1. Inject the API credential

Set OPENROUTER_API_KEY with your platform's process environment or secret manager. Keep only env:OPENROUTER_API_KEY in YAML.

2. Configure the OpenRouter route

Run colossus -w . config effective, edit the reported resolution.configPath, and keep its required storage block and any intended custom settings. Apply this validated overlay. The example uses OpenRouter's openrouter/free route; replace it with another exact catalog identifier and its limits when you need a specific model.

schemaVersion: 2
providers:
  profiles:
    openrouter-provider:
      kind: open_ai_compatible
      baseUrl: https://openrouter.ai/api/v1
      credentialReference: env:OPENROUTER_API_KEY
      chatCompletionsOutputTokenParameter: max_tokens
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

The API path remains in baseUrl. Under an isolating boundary, the sandbox receives only the exact origin; acknowledged full access needs no duplicate grant and an origin entry does not narrow ambient authority. This guide uses the adapter's standard bearer authentication. Do not add provider-specific headers that are not fields in the current Colossus provider schema.

The example explicitly selects the legacy-compatible max_tokens request field. If the exact routed model rejects that field and requires the modern Chat Completions name, change only chatCompletionsOutputTokenParameter to max_completion_tokens and rerun the model diagnostic. Colossus retains maxOutputTokens as the one canonical model budget and never probes by resubmitting a failed generation.

3. Confirm model visibility and readiness

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

Select a model ID exactly as the catalog returns it. Update context and output limits and capability flags for that same model before using it.

4. Send one bounded model turn

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

Expected result

The OpenRouter catalog is visible, the primary route names openrouter, diagnostics succeed, and the run returns connected.

Verification

Run colossus -w . config show and confirm that the output contains only the environment reference, exact model ID, API prefix, and any isolation-only sandbox origin—not the credential value. Under full access, confirm config effective reports ambient network authority.

Failure path

  • Credential unavailable or HTTP 401: confirm OPENROUTER_API_KEY is present in the Colossus process environment, then rerun provider doctor openrouter-provider.
  • A model is not visible: run provider models openrouter-provider and use an exact catalog identifier that the account can access.
  • The provider works but generation fails: correct the selected model's limits and chatCompletionsOutputTokenParameter, toolCalls, or streaming declarations, then rerun models doctor openrouter.
  • The origin is denied under isolation: keep /api/v1 in baseUrl and grant only https://openrouter.ai in the sandbox.

Next step

Review the compatibility boundary in Providers and models and the operator workflow in Providers and routing.