nodmix 2026.5.25

package/docs/providers/cerebras.md

@@ -0,0 +1,130 @@
+---
+summary: "Cerebras setup (auth + model selection)"
+title: "Cerebras"
+read_when:
+  - You want to use Cerebras with Nodmix
+  - You need the Cerebras API key env var or CLI auth choice
+---
+
+[Cerebras](https://www.cerebras.ai) provides high-speed OpenAI-compatible inference on custom inference hardware. Nodmix includes a bundled Cerebras provider plugin with a static four-model catalog.
+
+| Property        | Value                                    |
+| --------------- | ---------------------------------------- |
+| Provider id     | `cerebras`                               |
+| Plugin          | bundled, `enabledByDefault: true`        |
+| Auth env var    | `CEREBRAS_API_KEY`                       |
+| Onboarding flag | `--auth-choice cerebras-api-key`         |
+| Direct CLI flag | `--cerebras-api-key <key>`               |
+| API             | OpenAI-compatible (`openai-completions`) |
+| Base URL        | `https://api.cerebras.ai/v1`             |
+| Default model   | `cerebras/zai-glm-4.7`                   |
+
+## Getting started
+
+<Steps>
+  <Step title="Get an API key">
+    Create an API key in the [Cerebras Cloud Console](https://cloud.cerebras.ai).
+  </Step>
+  <Step title="Run onboarding">
+    <CodeGroup>
+
+```bash Onboarding
+nodmix onboard --auth-choice cerebras-api-key
+```
+
+```bash Direct flag
+nodmix onboard --non-interactive \
+  --auth-choice cerebras-api-key \
+  --cerebras-api-key "$CEREBRAS_API_KEY"
+```
+
+```bash Env only
+export CEREBRAS_API_KEY=csk-...
+```
+
+    </CodeGroup>
+
+  </Step>
+  <Step title="Verify models are available">
+    ```bash
+    nodmix models list --provider cerebras
+    ```
+
+    The list should include all four bundled models. If `CEREBRAS_API_KEY` is unresolved, `nodmix models status --json` reports the missing credential under `auth.unusableProfiles`.
+
+  </Step>
+</Steps>
+
+## Non-interactive setup
+
+```bash
+nodmix onboard --non-interactive \
+  --mode local \
+  --auth-choice cerebras-api-key \
+  --cerebras-api-key "$CEREBRAS_API_KEY"
+```
+
+## Built-in catalog
+
+Nodmix ships a static Cerebras catalog that mirrors the public OpenAI-compatible endpoint. All four models share a 128k context and 8,192 max-output tokens.
+
+| Model ref                                 | Name                 | Reasoning | Notes                                  |
+| ----------------------------------------- | -------------------- | --------- | -------------------------------------- |
+| `cerebras/zai-glm-4.7`                    | Z.ai GLM 4.7         | yes       | Default model; preview reasoning model |
+| `cerebras/gpt-oss-120b`                   | GPT OSS 120B         | yes       | Production reasoning model             |
+| `cerebras/qwen-3-235b-a22b-instruct-2507` | Qwen 3 235B Instruct | no        | Preview non-reasoning model            |
+| `cerebras/llama3.1-8b`                    | Llama 3.1 8B         | no        | Production speed-focused model         |
+
+<Warning>
+  Cerebras marks `zai-glm-4.7` and `qwen-3-235b-a22b-instruct-2507` as preview models, and `llama3.1-8b` plus `qwen-3-235b-a22b-instruct-2507` are documented for deprecation on May 27, 2026. Check Cerebras' supported-models page before relying on them for production workloads.
+</Warning>
+
+## Manual config
+
+The bundled plugin usually means you only need the API key. Use explicit `models.providers.cerebras` config when you want to override model metadata or run in `mode: "merge"` against the static catalog:
+
+```json5
+{
+  env: { CEREBRAS_API_KEY: "csk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "cerebras/zai-glm-4.7" },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      cerebras: {
+        baseUrl: "https://api.cerebras.ai/v1",
+        apiKey: "${CEREBRAS_API_KEY}",
+        api: "openai-completions",
+        models: [
+          { id: "zai-glm-4.7", name: "Z.ai GLM 4.7" },
+          { id: "gpt-oss-120b", name: "GPT OSS 120B" },
+        ],
+      },
+    },
+  },
+}
+```
+
+<Note>
+  If the Gateway runs as a daemon (launchd, systemd, Docker), make sure `CEREBRAS_API_KEY` is available to that process — for example in `~/.nodmix/.env` or through `env.shellEnv`. A key exported only in an interactive shell will not help a managed service unless the env is imported separately.
+</Note>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model providers" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Thinking modes" href="/tools/thinking" icon="brain">
+    Reasoning effort levels for the two reasoning-capable Cerebras models.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
+    Agent defaults and model configuration.
+  </Card>
+  <Card title="Models FAQ" href="/help/faq-models" icon="circle-question">
+    Auth profiles, switching models, and resolving "no profile" errors.
+  </Card>
+</CardGroup>

package/docs/providers/chutes.md

@@ -0,0 +1,153 @@
+---
+summary: "Chutes setup (OAuth or API key, model discovery, aliases)"
+title: "Chutes"
+read_when:
+  - You want to use Chutes with Nodmix
+  - You need the OAuth or API key setup path
+  - You want the default model, aliases, or discovery behavior
+---
+
+[Chutes](https://chutes.ai) exposes open-source model catalogs through an
+OpenAI-compatible API. Nodmix supports both browser OAuth and direct API-key
+auth for the bundled `chutes` provider.
+
+| Property | Value                        |
+| -------- | ---------------------------- |
+| Provider | `chutes`                     |
+| API      | OpenAI-compatible            |
+| Base URL | `https://llm.chutes.ai/v1`   |
+| Auth     | OAuth or API key (see below) |
+
+## Getting started
+
+<Tabs>
+  <Tab title="OAuth">
+    <Steps>
+      <Step title="Run the OAuth onboarding flow">
+        ```bash
+        nodmix onboard --auth-choice chutes
+        ```
+        Nodmix launches the browser flow locally, or shows a URL + redirect-paste
+        flow on remote/headless hosts. OAuth tokens auto-refresh through Nodmix auth
+        profiles.
+      </Step>
+      <Step title="Verify the default model">
+        After onboarding, the default model is set to
+        `chutes/zai-org/GLM-4.7-TEE` and the bundled Chutes catalog is
+        registered.
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="API key">
+    <Steps>
+      <Step title="Get an API key">
+        Create a key at
+        [chutes.ai/settings/api-keys](https://chutes.ai/settings/api-keys).
+      </Step>
+      <Step title="Run the API key onboarding flow">
+        ```bash
+        nodmix onboard --auth-choice chutes-api-key
+        ```
+      </Step>
+      <Step title="Verify the default model">
+        After onboarding, the default model is set to
+        `chutes/zai-org/GLM-4.7-TEE` and the bundled Chutes catalog is
+        registered.
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
+<Note>
+Both auth paths register the bundled Chutes catalog and set the default model to
+`chutes/zai-org/GLM-4.7-TEE`. Runtime environment variables: `CHUTES_API_KEY`,
+`CHUTES_OAUTH_TOKEN`.
+</Note>
+
+## Discovery behavior
+
+When Chutes auth is available, Nodmix queries the Chutes catalog with that
+credential and uses the discovered models. If discovery fails, Nodmix falls
+back to a bundled static catalog so onboarding and startup still work.
+
+## Default aliases
+
+Nodmix registers three convenience aliases for the bundled Chutes catalog:
+
+| Alias           | Target model                                          |
+| --------------- | ----------------------------------------------------- |
+| `chutes-fast`   | `chutes/zai-org/GLM-4.7-FP8`                          |
+| `chutes-pro`    | `chutes/deepseek-ai/DeepSeek-V3.2-TEE`                |
+| `chutes-vision` | `chutes/chutesai/Mistral-Small-3.2-24B-Instruct-2506` |
+
+## Built-in starter catalog
+
+The bundled fallback catalog includes current Chutes refs:
+
+| Model ref                                             |
+| ----------------------------------------------------- |
+| `chutes/zai-org/GLM-4.7-TEE`                          |
+| `chutes/zai-org/GLM-5-TEE`                            |
+| `chutes/deepseek-ai/DeepSeek-V3.2-TEE`                |
+| `chutes/deepseek-ai/DeepSeek-R1-0528-TEE`             |
+| `chutes/moonshotai/Kimi-K2.5-TEE`                     |
+| `chutes/chutesai/Mistral-Small-3.2-24B-Instruct-2506` |
+| `chutes/Qwen/Qwen3-Coder-Next-TEE`                    |
+| `chutes/openai/gpt-oss-120b-TEE`                      |
+
+## Config example
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "chutes/zai-org/GLM-4.7-TEE" },
+      models: {
+        "chutes/zai-org/GLM-4.7-TEE": { alias: "Chutes GLM 4.7" },
+        "chutes/deepseek-ai/DeepSeek-V3.2-TEE": { alias: "Chutes DeepSeek V3.2" },
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="OAuth overrides">
+    You can customize the OAuth flow with optional environment variables:
+
+    | Variable | Purpose |
+    | -------- | ------- |
+    | `CHUTES_CLIENT_ID` | Custom OAuth client ID |
+    | `CHUTES_CLIENT_SECRET` | Custom OAuth client secret |
+    | `CHUTES_OAUTH_REDIRECT_URI` | Custom redirect URI |
+    | `CHUTES_OAUTH_SCOPES` | Custom OAuth scopes |
+
+    See the [Chutes OAuth docs](https://chutes.ai/docs/sign-in-with-chutes/overview)
+    for redirect-app requirements and help.
+
+  </Accordion>
+
+  <Accordion title="Notes">
+    - API-key and OAuth discovery both use the same `chutes` provider id.
+    - Chutes models are registered as `chutes/<model-id>`.
+    - If discovery fails at startup, the bundled static catalog is used automatically.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Provider rules, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config schema including provider settings.
+  </Card>
+  <Card title="Chutes" href="https://chutes.ai" icon="arrow-up-right-from-square">
+    Chutes dashboard and API docs.
+  </Card>
+  <Card title="Chutes API keys" href="https://chutes.ai/settings/api-keys" icon="key">
+    Create and manage Chutes API keys.
+  </Card>
+</CardGroup>

package/docs/providers/claude-max-api-proxy.md

@@ -0,0 +1,188 @@
+---
+summary: "Community proxy to expose Claude subscription credentials as an OpenAI-compatible endpoint"
+read_when:
+  - You want to use Claude Max subscription with OpenAI-compatible tools
+  - You want a local API server that wraps Claude Code CLI
+  - You want to evaluate subscription-based vs API-key-based Anthropic access
+title: "Claude Max API proxy"
+---
+
+**claude-max-api-proxy** is a community tool that exposes your Claude Max/Pro subscription as an OpenAI-compatible API endpoint. This allows you to use your subscription with any tool that supports the OpenAI API format.
+
+<Warning>
+This path is technical compatibility only. Anthropic has blocked some subscription
+usage outside Claude Code in the past. You must decide for yourself whether to use
+it and verify Anthropic's current terms before relying on it.
+</Warning>
+
+## Why use this?
+
+| Approach                | Cost                                                | Best For                                   |
+| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
+| Anthropic API           | Pay per token (~$15/M input, $75/M output for Opus) | Production apps, high volume               |
+| Claude Max subscription | $200/month flat                                     | Personal use, development, unlimited usage |
+
+If you have a Claude Max subscription and want to use it with OpenAI-compatible tools, this proxy may reduce cost for some workflows. API keys remain the clearer policy path for production use.
+
+## How it works
+
+```
+Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
+     (OpenAI format)              (converts format)      (uses your login)
+```
+
+The proxy:
+
+1. Accepts OpenAI-format requests at `http://localhost:3456/v1/chat/completions`
+2. Converts them to Claude Code CLI commands
+3. Returns responses in OpenAI format (streaming supported)
+
+## Getting started
+
+<Steps>
+  <Step title="Install the proxy">
+    Requires Node.js 20+ and Claude Code CLI.
+
+    ```bash
+    npm install -g claude-max-api-proxy
+
+    # Verify Claude CLI is authenticated
+    claude --version
+    ```
+
+  </Step>
+  <Step title="Start the server">
+    ```bash
+    claude-max-api
+    # Server runs at http://localhost:3456
+    ```
+  </Step>
+  <Step title="Test the proxy">
+    ```bash
+    # Health check
+    curl http://localhost:3456/health
+
+    # List models
+    curl http://localhost:3456/v1/models
+
+    # Chat completion
+    curl http://localhost:3456/v1/chat/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "claude-opus-4",
+        "messages": [{"role": "user", "content": "Hello!"}]
+      }'
+    ```
+
+  </Step>
+  <Step title="Configure Nodmix">
+    Point Nodmix at the proxy as a custom OpenAI-compatible endpoint:
+
+    ```json5
+    {
+      env: {
+        OPENAI_API_KEY: "not-needed",
+        OPENAI_BASE_URL: "http://localhost:3456/v1",
+      },
+      agents: {
+        defaults: {
+          model: { primary: "openai/claude-opus-4" },
+        },
+      },
+    }
+    ```
+
+  </Step>
+</Steps>
+
+## Built-in catalog
+
+| Model ID          | Maps To         |
+| ----------------- | --------------- |
+| `claude-opus-4`   | Claude Opus 4   |
+| `claude-sonnet-4` | Claude Sonnet 4 |
+| `claude-haiku-4`  | Claude Haiku 4  |
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Proxy-style OpenAI-compatible notes">
+    This path uses the same proxy-style OpenAI-compatible route as other custom
+    `/v1` backends:
+
+    - Native OpenAI-only request shaping does not apply
+    - No `service_tier`, no Responses `store`, no prompt-cache hints, and no
+      OpenAI reasoning-compat payload shaping
+    - Hidden Nodmix attribution headers (`originator`, `version`, `User-Agent`)
+      are not injected on the proxy URL
+
+  </Accordion>
+
+  <Accordion title="Auto-start on macOS with LaunchAgent">
+    Create a LaunchAgent to run the proxy automatically:
+
+    ```bash
+    cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF'
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+    <plist version="1.0">
+    <dict>
+      <key>Label</key>
+      <string>com.claude-max-api</string>
+      <key>RunAtLoad</key>
+      <true/>
+      <key>KeepAlive</key>
+      <true/>
+      <key>ProgramArguments</key>
+      <array>
+        <string>/usr/local/bin/node</string>
+        <string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string>
+      </array>
+      <key>EnvironmentVariables</key>
+      <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string>
+      </dict>
+    </dict>
+    </plist>
+    EOF
+
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## Links
+
+- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy)
+- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy)
+- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues)
+
+## Notes
+
+- This is a **community tool**, not officially supported by Anthropic or Nodmix
+- Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated
+- The proxy runs locally and does not send data to any third-party servers
+- Streaming responses are fully supported
+
+<Note>
+For native Anthropic integration with Claude CLI or API keys, see [Anthropic provider](/providers/anthropic). For OpenAI/Codex subscriptions, see [OpenAI provider](/providers/openai).
+</Note>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Anthropic provider" href="/providers/anthropic" icon="bolt">
+    Native Nodmix integration with Claude CLI or API keys.
+  </Card>
+  <Card title="OpenAI provider" href="/providers/openai" icon="robot">
+    For OpenAI/Codex subscriptions.
+  </Card>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Overview of all providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration" icon="gear">
+    Full config reference.
+  </Card>
+</CardGroup>

package/docs/providers/cloudflare-ai-gateway.md

@@ -0,0 +1,119 @@
+---
+summary: "Cloudflare AI Gateway setup (auth + model selection)"
+title: "Cloudflare AI gateway"
+read_when:
+  - You want to use Cloudflare AI Gateway with Nodmix
+  - You need the account ID, gateway ID, or API key env var
+---
+
+Cloudflare AI Gateway sits in front of provider APIs and lets you add analytics, caching, and controls. For Anthropic, Nodmix uses the Anthropic Messages API through your Gateway endpoint.
+
+| Property      | Value                                                                                    |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| Provider      | `cloudflare-ai-gateway`                                                                  |
+| Base URL      | `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`               |
+| Default model | `cloudflare-ai-gateway/claude-sonnet-4-6`                                                |
+| API key       | `CLOUDFLARE_AI_GATEWAY_API_KEY` (your provider API key for requests through the Gateway) |
+
+<Note>
+For Anthropic models routed through Cloudflare AI Gateway, use your **Anthropic API key** as the provider key.
+</Note>
+
+When thinking is enabled for Anthropic Messages models, Nodmix strips trailing
+assistant prefill turns before sending the payload through Cloudflare AI Gateway.
+Anthropic rejects response prefilling with extended thinking, while ordinary
+non-thinking prefill remains available.
+
+## Getting started
+
+<Steps>
+  <Step title="Set the provider API key and Gateway details">
+    Run onboarding and choose the Cloudflare AI Gateway auth option:
+
+    ```bash
+    nodmix onboard --auth-choice cloudflare-ai-gateway-api-key
+    ```
+
+    This prompts for your account ID, gateway ID, and API key.
+
+  </Step>
+  <Step title="Set a default model">
+    Add the model to your Nodmix config:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-6" },
+        },
+      },
+    }
+    ```
+
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    nodmix models list --provider cloudflare-ai-gateway
+    ```
+  </Step>
+</Steps>
+
+## Non-interactive example
+
+For scripted or CI setups, pass all values on the command line:
+
+```bash
+nodmix onboard --non-interactive \
+  --mode local \
+  --auth-choice cloudflare-ai-gateway-api-key \
+  --cloudflare-ai-gateway-account-id "your-account-id" \
+  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
+  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
+```
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Authenticated gateways">
+    If you enabled Gateway authentication in Cloudflare, add the `cf-aig-authorization` header. This is **in addition to** your provider API key.
+
+    ```json5
+    {
+      models: {
+        providers: {
+          "cloudflare-ai-gateway": {
+            headers: {
+              "cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    <Tip>
+    The `cf-aig-authorization` header authenticates with the Cloudflare Gateway itself, while the provider API key (for example, your Anthropic key) authenticates with the upstream provider.
+    </Tip>
+
+  </Accordion>
+
+  <Accordion title="Environment note">
+    If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process.
+
+    <Warning>
+    A key exported only in an interactive shell will not help a launchd/systemd daemon unless that environment is imported there as well. Set the key in `~/.nodmix/.env` or via `env.shellEnv` to ensure the gateway process can read it.
+    </Warning>
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
+    General troubleshooting and FAQ.
+  </Card>
+</CardGroup>