Add real Cerebras provider with OpenPaths fallback

lee101 · claude · lee101 · commit d27fef9d24e1 · 2026-06-08T00:47:11.000Z
Add a direct Cerebras provider (CEREBRAS_API_KEY, https://api.cerebras.ai) instead of routing Cerebras models through OpenRouter. The cerebras/* models (gpt-oss-120b, zai-glm-4.7) auto-detect to a direct Cerebras key when present and otherwise fall back to OpenPaths (OPENPATHS_API_KEY), which also serves the Cerebras-hosted open-weight models. - model-provider-info: add Cerebras provider, base-url override (CEREBRAS_BASE_URL), prefix normalization, and env-backed auto-detection with OpenPaths fallback - models.json: rename slugs openpaths/* -> cerebras/* - README: document provider env-var auto-detection - scripts/e2e_cerebras_openpaths.sh + .env.example: e2e smoke test via OpenPaths Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
diff --git a/.env.example b/.env.example
@@ -0,0 +1,16 @@
+# Copy to .env (gitignored) and fill in real keys for local / e2e testing.
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+
+# Cerebras — fast open-weight coding models (gpt-oss-120b, zai-glm-4.7).
+# Direct key (https://api.cerebras.ai). When set, cerebras/* models use it directly.
+CEREBRAS_API_KEY=csk-...
+
+# OpenPaths (https://openpaths.io) — a router that also serves the Cerebras-hosted
+# models, so this key alone is enough to reach cerebras/* models.
+OPENPATHS_API_KEY=op-...
+
+# Optional endpoint overrides
+# CEREBRAS_BASE_URL=https://api.cerebras.ai
+# OPENPATHS_BASE_URL=https://openpaths.io
diff --git a/README.md b/README.md
@@ -54,6 +54,34 @@ export OPENAI_API_KEY=sk-...
 codex-infinity "your prompt"
 ```
 
+### Model providers (auto-detected)
+
+`codex-infinity` auto-detects which provider to use from the model slug and the API keys present in your environment — no `config.toml` edits required. Export a key and select a matching model with `-m`:
+
+| Provider | Env var | Example models |
+|----------|---------|----------------|
+| OpenAI | `OPENAI_API_KEY` | `gpt-5.4`, `o3` |
+| Cerebras | `CEREBRAS_API_KEY` | `cerebras/gpt-oss-120b`, `cerebras/zai-glm-4.7` |
+| OpenPaths | `OPENPATHS_API_KEY` | `openpaths/auto`, `cerebras/gpt-oss-120b`, `composer-2.5` |
+| OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-opus-4.6`, `google/gemini-3.5-flash` |
+| Google Gemini | `GEMINI_API_KEY` | `google/gemini-3.5-flash` |
+| Z.AI (Zhipu) | `ZAI_API_KEY` | `glm-4.7`, `z-ai/glm-5` |
+| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
+| Cursor | `CURSOR_API_KEY` | `cursor/composer-2.5` |
+| Local (OSS) | — (`--oss`) | LM Studio / Ollama models |
+
+**Cerebras** runs the fast open-weight coding models (`gpt-oss-120b`, `zai-glm-4.7`). A `cerebras/*` model prefers a direct Cerebras key (`CEREBRAS_API_KEY`, `https://api.cerebras.ai`) and otherwise falls back to **OpenPaths** ([openpaths.io](https://openpaths.io)), a router that also serves the Cerebras-hosted models — so a single `OPENPATHS_API_KEY` is enough to reach them. Override the endpoints with `CEREBRAS_BASE_URL` / `OPENPATHS_BASE_URL` if needed.
+
+```shell
+# Direct Cerebras
+export CEREBRAS_API_KEY=csk-...
+codex-infinity -m cerebras/gpt-oss-120b "refactor this module"
+
+# Or via OpenPaths (also serves Cerebras models)
+export OPENPATHS_API_KEY=op-...
+codex-infinity -m cerebras/zai-glm-4.7 "explain this bug"
+```
+
 ## CLI flags
 
 | Flag | Description |
diff --git a/codex-rs/model-provider-info/src/lib.rs b/codex-rs/model-provider-info/src/lib.rs
@@ -46,6 +46,8 @@ const ZHIPU_PROVIDER_NAME: &str = "Z.AI (Zhipu)";
 pub const ZHIPU_PROVIDER_ID: &str = "zhipu";
 const DEEPSEEK_PROVIDER_NAME: &str = "DeepSeek";
 pub const DEEPSEEK_PROVIDER_ID: &str = "deepseek";
+const CEREBRAS_PROVIDER_NAME: &str = "Cerebras";
+pub const CEREBRAS_PROVIDER_ID: &str = "cerebras";
 const AMAZON_BEDROCK_PROVIDER_NAME: &str = "Amazon Bedrock";
 pub const AMAZON_BEDROCK_PROVIDER_ID: &str = "amazon-bedrock";
 pub const AMAZON_BEDROCK_DEFAULT_BASE_URL: &str =
@@ -477,6 +479,30 @@ impl ModelProviderInfo {
         }
     }
 
+    pub fn create_cerebras_provider() -> ModelProviderInfo {
+        ModelProviderInfo {
+            name: CEREBRAS_PROVIDER_NAME.into(),
+            base_url: Some(cerebras_base_url()),
+            env_key: Some("CEREBRAS_API_KEY".into()),
+            env_key_instructions: Some(
+                "Get your API key from https://cloud.cerebras.ai and set CEREBRAS_API_KEY".into(),
+            ),
+            experimental_bearer_token: None,
+            auth: None,
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: None,
+            env_http_headers: None,
+            request_max_retries: None,
+            stream_max_retries: None,
+            stream_idle_timeout_ms: None,
+            websocket_connect_timeout_ms: None,
+            requires_openai_auth: false,
+            supports_websockets: false,
+            ..Default::default()
+        }
+    }
+
     pub fn create_deepseek_provider() -> ModelProviderInfo {
         ModelProviderInfo {
             name: DEEPSEEK_PROVIDER_NAME.into(),
@@ -537,7 +563,13 @@ impl ModelProviderInfo {
         if self.name == GEMINI_PROVIDER_NAME {
             slug.strip_prefix("google/").unwrap_or(slug)
         } else if self.name == OPENPATHS_PROVIDER_NAME {
-            slug.strip_prefix("openpaths/").unwrap_or(slug)
+            // OpenPaths is a router that can also serve Cerebras-hosted models,
+            // so accept either the `openpaths/` or `cerebras/` prefix.
+            slug.strip_prefix("openpaths/")
+                .or_else(|| slug.strip_prefix("cerebras/"))
+                .unwrap_or(slug)
+        } else if self.name == CEREBRAS_PROVIDER_NAME {
+            slug.strip_prefix("cerebras/").unwrap_or(slug)
         } else if self.name == CURSOR_PROVIDER_NAME {
             slug.strip_prefix("cursor/").unwrap_or(slug)
         } else if self.name == ZHIPU_PROVIDER_NAME {
@@ -589,6 +621,7 @@ pub fn built_in_model_providers(
         (GEMINI_PROVIDER_ID, P::create_gemini_provider()),
         (ZHIPU_PROVIDER_ID, P::create_zhipu_provider()),
         (DEEPSEEK_PROVIDER_ID, P::create_deepseek_provider()),
+        (CEREBRAS_PROVIDER_ID, P::create_cerebras_provider()),
         (AMAZON_BEDROCK_PROVIDER_ID, amazon_bedrock_provider),
         (
             OLLAMA_OSS_PROVIDER_ID,
@@ -625,6 +658,21 @@ fn openpaths_base_url() -> String {
         .unwrap_or_else(|| "https://openpaths.io/v1".to_string())
 }
 
+fn cerebras_base_url() -> String {
+    std::env::var("CEREBRAS_BASE_URL")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .map(|value| {
+            let trimmed = value.trim().trim_end_matches('/');
+            if trimmed.ends_with("/v1") {
+                trimmed.to_string()
+            } else {
+                format!("{trimmed}/v1")
+            }
+        })
+        .unwrap_or_else(|| "https://api.cerebras.ai/v1".to_string())
+}
+
 fn cursor_base_url() -> String {
     std::env::var("CURSOR_BASE_URL")
         .ok()
@@ -638,9 +686,7 @@ fn is_composer_model_slug(lower: &str) -> bool {
         .strip_prefix("openpaths/")
         .or_else(|| lower.strip_prefix("cursor/"))
         .unwrap_or(lower);
-    slug == "composer-2.5"
-        || slug == "composer-2.5-fast"
-        || slug.starts_with("composer-2.5-")
+    slug == "composer-2.5" || slug == "composer-2.5-fast" || slug.starts_with("composer-2.5-")
 }
 
 pub fn infer_builtin_provider_id_for_model(model: &str) -> Option<&'static str> {
@@ -694,6 +740,14 @@ pub fn infer_builtin_provider_id_for_model(model: &str) -> Option<&'static str>
         Some(("openpaths", _)) if non_empty_env_var("OPENPATHS_API_KEY") => {
             Some(OPENPATHS_PROVIDER_ID)
         }
+        // Prefer a direct Cerebras key, but fall back to OpenPaths, which also
+        // serves the Cerebras-hosted open-weight models.
+        Some(("cerebras", _)) if non_empty_env_var("CEREBRAS_API_KEY") => {
+            Some(CEREBRAS_PROVIDER_ID)
+        }
+        Some(("cerebras", _)) if non_empty_env_var("OPENPATHS_API_KEY") => {
+            Some(OPENPATHS_PROVIDER_ID)
+        }
         Some(("cursor", _)) if non_empty_env_var("CURSOR_API_KEY") => Some(CURSOR_PROVIDER_ID),
         Some(("deepseek", _)) if non_empty_env_var("DEEPSEEK_API_KEY") => {
             Some(DEEPSEEK_PROVIDER_ID)
diff --git a/codex-rs/model-provider-info/src/model_provider_info_tests.rs b/codex-rs/model-provider-info/src/model_provider_info_tests.rs
@@ -297,6 +297,32 @@ fn openpaths_provider_normalizes_openpaths_prefix() {
     );
 }
 
+#[test]
+fn cerebras_provider_normalizes_cerebras_prefix() {
+    let provider = ModelProviderInfo::create_cerebras_provider();
+    assert_eq!(provider.env_key.as_deref(), Some("CEREBRAS_API_KEY"));
+    assert_eq!(
+        provider.base_url.as_deref(),
+        Some("https://api.cerebras.ai/v1")
+    );
+    assert_eq!(
+        provider.effective_model_name("cerebras/gpt-oss-120b"),
+        "gpt-oss-120b"
+    );
+    assert_eq!(provider.effective_model_name("zai-glm-4.7"), "zai-glm-4.7");
+}
+
+#[test]
+fn openpaths_provider_normalizes_cerebras_prefix() {
+    // OpenPaths is a router that also serves the Cerebras-hosted models, so a
+    // `cerebras/` slug routed to OpenPaths must drop the prefix too.
+    let provider = ModelProviderInfo::create_openpaths_provider();
+    assert_eq!(
+        provider.effective_model_name("cerebras/gpt-oss-120b"),
+        "gpt-oss-120b"
+    );
+}
+
 #[test]
 fn cursor_provider_normalizes_cursor_prefix() {
     let provider = ModelProviderInfo::create_cursor_provider();
@@ -315,6 +341,7 @@ fn infer_builtin_provider_prefers_env_backed_routes() {
     let _gemini_remove_guard = EnvVarGuard::remove("GEMINI_API_KEY");
     let _openrouter_remove_guard = EnvVarGuard::remove("OPENROUTER_API_KEY");
     let _cursor_remove_guard = EnvVarGuard::remove("CURSOR_API_KEY");
+    let _cerebras_remove_guard = EnvVarGuard::remove("CEREBRAS_API_KEY");
     let openpaths_remove_guard = EnvVarGuard::remove("OPENPATHS_API_KEY");
     assert_eq!(
         infer_builtin_provider_id_for_model("google/gemini-3.5-flash"),
@@ -370,6 +397,19 @@ fn infer_builtin_provider_prefers_env_backed_routes() {
         infer_builtin_provider_id_for_model("composer-2.5-fast"),
         Some(OPENPATHS_PROVIDER_ID)
     );
+    // With only an OpenPaths key, Cerebras-hosted models route through OpenPaths.
+    assert_eq!(
+        infer_builtin_provider_id_for_model("cerebras/gpt-oss-120b"),
+        Some(OPENPATHS_PROVIDER_ID)
+    );
+
+    // A direct Cerebras key takes precedence over the OpenPaths fallback.
+    let cerebras_set_guard = EnvVarGuard::set("CEREBRAS_API_KEY", "csk-key");
+    assert_eq!(
+        infer_builtin_provider_id_for_model("cerebras/zai-glm-4.7"),
+        Some(CEREBRAS_PROVIDER_ID)
+    );
+    drop(cerebras_set_guard);
 
     drop(_openpaths_set_guard);
     let _cursor_set_guard = EnvVarGuard::set("CURSOR_API_KEY", "cursor-key");
diff --git a/codex-rs/models-manager/models.json b/codex-rs/models-manager/models.json
@@ -588,6 +588,100 @@
       "supports_search_tool": true,
       "additional_speed_tiers": [],
       "supports_reasoning_summaries": true
+    },
+    {
+      "slug": "cerebras/gpt-oss-120b",
+      "display_name": "GPT-OSS 120B (Cerebras)",
+      "description": "OpenAI gpt-oss-120b on Cerebras (~3000 tok/s open-weight coding model). Auto-routes to a direct Cerebras key (CEREBRAS_API_KEY) or falls back to OpenPaths (OPENPATHS_API_KEY).",
+      "default_reasoning_level": "medium",
+      "supported_reasoning_levels": [
+        {
+          "effort": "low",
+          "description": "Fast responses with lighter reasoning"
+        },
+        {
+          "effort": "medium",
+          "description": "Balances speed and reasoning depth"
+        },
+        {
+          "effort": "high",
+          "description": "Greater reasoning depth for complex problems"
+        }
+      ],
+      "shell_type": "shell_command",
+      "visibility": "list",
+      "supported_in_api": true,
+      "priority": 42,
+      "upgrade": null,
+      "base_instructions": "You are Codex, a coding agent. Follow the user's instructions and use available tools to complete software engineering tasks.",
+      "supports_reasoning_summaries": false,
+      "support_verbosity": false,
+      "default_verbosity": null,
+      "apply_patch_tool_type": "freeform",
+      "web_search_tool_type": "text",
+      "truncation_policy": {
+        "mode": "tokens",
+        "limit": 10000
+      },
+      "supports_parallel_tool_calls": true,
+      "supports_image_detail_original": false,
+      "context_window": 131072,
+      "max_context_window": 131072,
+      "auto_compact_token_limit": null,
+      "experimental_supported_tools": [],
+      "input_modalities": [
+        "text"
+      ],
+      "availability_nux": null,
+      "additional_speed_tiers": [],
+      "supports_search_tool": false
+    },
+    {
+      "slug": "cerebras/zai-glm-4.7",
+      "display_name": "GLM-4.7 (Cerebras)",
+      "description": "Zhipu GLM-4.7 on Cerebras — strong reasoning and coding. Auto-routes to a direct Cerebras key (CEREBRAS_API_KEY) or falls back to OpenPaths (OPENPATHS_API_KEY).",
+      "default_reasoning_level": "medium",
+      "supported_reasoning_levels": [
+        {
+          "effort": "low",
+          "description": "Fast responses with lighter reasoning"
+        },
+        {
+          "effort": "medium",
+          "description": "Balances speed and reasoning depth"
+        },
+        {
+          "effort": "high",
+          "description": "Greater reasoning depth for complex problems"
+        }
+      ],
+      "shell_type": "shell_command",
+      "visibility": "list",
+      "supported_in_api": true,
+      "priority": 43,
+      "upgrade": null,
+      "base_instructions": "You are Codex, a coding agent. Follow the user's instructions and use available tools to complete software engineering tasks.",
+      "supports_reasoning_summaries": false,
+      "support_verbosity": false,
+      "default_verbosity": null,
+      "apply_patch_tool_type": "freeform",
+      "web_search_tool_type": "text",
+      "truncation_policy": {
+        "mode": "tokens",
+        "limit": 10000
+      },
+      "supports_parallel_tool_calls": true,
+      "supports_image_detail_original": false,
+      "context_window": 131072,
+      "max_context_window": 131072,
+      "auto_compact_token_limit": null,
+      "experimental_supported_tools": [],
+      "input_modalities": [
+        "text"
+      ],
+      "availability_nux": null,
+      "additional_speed_tiers": [],
+      "supports_search_tool": false
     }
   ]
 }
diff --git a/codex-rs/models-manager/src/manager_tests.rs b/codex-rs/models-manager/src/manager_tests.rs
@@ -842,4 +842,10 @@ fn bundled_models_json_roundtrips() {
             .any(|model| model.slug == "deepseek/deepseek-v4-flash"),
         "bundled models.json should include a DeepSeek model"
     );
+    for slug in ["cerebras/gpt-oss-120b", "cerebras/zai-glm-4.7"] {
+        assert!(
+            response.models.iter().any(|model| model.slug == slug),
+            "bundled models.json should include the Cerebras model {slug}"
+        );
+    }
 }
diff --git a/scripts/e2e_cerebras_openpaths.sh b/scripts/e2e_cerebras_openpaths.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# E2E smoke test: verify the Cerebras-hosted models are reachable through OpenPaths.
+#
+# Codex's `cerebras/*` models prefer a direct CEREBRAS_API_KEY and otherwise fall
+# back to OpenPaths (openpaths.io), which also serves the Cerebras-hosted
+# open-weight models. This script confirms the key works and the models respond.
+#
+# Usage:
+#   ./scripts/e2e_cerebras_openpaths.sh
+# Reads OPENPATHS_API_KEY (and optional OPENPATHS_BASE_URL) from the environment
+# or from a gitignored .env at the repo root.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if [[ -f "${repo_root}/.env" ]]; then
+  # shellcheck disable=SC1091
+  set -a; source "${repo_root}/.env"; set +a
+fi
+
+: "${OPENPATHS_API_KEY:?Set OPENPATHS_API_KEY (e.g. in ${repo_root}/.env)}"
+base_url="${OPENPATHS_BASE_URL:-https://openpaths.io}"
+base_url="${base_url%/}"
+
+models=("gpt-oss-120b" "zai-glm-4.7")
+failed=0
+
+for model in "${models[@]}"; do
+  echo "== ${model} via ${base_url} =="
+  resp="$(curl -sS -m 60 "${base_url}/v1/chat/completions" \
+    -H "Authorization: Bearer ${OPENPATHS_API_KEY}" \
+    -H "Content-Type: application/json" \
+    -d "{\"model\":\"${model}\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with the single word: pong\"}],\"stream\":false}")"
+  content="$(printf '%s' "${resp}" | python3 -c 'import sys,json; print(json.load(sys.stdin)["choices"][0]["message"]["content"])' 2>/dev/null || true)"
+  if [[ -n "${content}" ]]; then
+    echo "  OK -> ${content}"
+  else
+    echo "  FAIL -> ${resp}"
+    failed=1
+  fi
+done
+
+if [[ "${failed}" -ne 0 ]]; then
+  echo "e2e: at least one Cerebras model failed via OpenPaths" >&2
+  exit 1
+fi
+echo "e2e: all Cerebras models reachable via OpenPaths"
