BYOK Providers¶

Bring Your Own Key (BYOK) mode connects to cloud AI providers using your API keys.

Overview¶

BYOK is the primary mode for production use:

• Full control: Use your own API keys and quotas
• Cost management: Pay directly to providers
• Model selection: Choose specific models for your tasks
• Privacy: Data goes directly to your chosen provider

Quick Setup¶

Open the BYOK provider and model picker in the TUI:

:connect byok

Or connect directly:

# 1. Set API key. Alternative: `superqode auth login anthropic` stores the
#    key in ~/.superqode/auth.json (0600) via a masked prompt.
export ANTHROPIC_API_KEY=sk-ant-...

# 2. Verify configuration
superqode providers test anthropic

# 3. Connect
superqode connect byok anthropic <anthropic-model>

Supported Providers¶

The picker combines SuperQode's first-class provider definitions with every provider in the cached models.dev catalog. New long-tail providers therefore appear without a SuperQode release when models.dev publishes an API endpoint, key variable, and model inventory. Run :connect byok and press R to refresh the catalog. First-class entries add tested routing, clearer grouping, and provider-specific setup guidance.

Tier 1 (First-Class Support)¶

Full optimization and testing:

Anthropic (Claude)¶

export ANTHROPIC_API_KEY=sk-ant-...
superqode connect byok anthropic <anthropic-balanced-model>

Documentation: docs.anthropic.com

OpenAI (GPT)¶

export OPENAI_API_KEY=sk-...
superqode connect byok openai <openai-model>

Documentation: platform.openai.com

Google AI (Gemini)¶

export GOOGLE_API_KEY=AIza...
superqode connect byok google gemini-3.1-pro-preview

Documentation: ai.google.dev

Z.AI (GLM)¶

export ZAI_API_KEY=...
superqode connect zai glm-5.2

The zai provider uses the first-party general endpoint https://api.z.ai/api/paas/v4. It does not use the restricted GLM Coding Plan endpoint. See the Z.AI provider guide for the TUI connection and the glm52-coding harness.

Meta (Muse Spark)¶

export META_MODEL_API_KEY=...
superqode connect byok meta muse-spark-1.1

Meta's model API is OpenAI-compatible at https://api.meta.ai/v1 (override with META_BASE_URL). The model list follows models.dev, so new Meta releases appear automatically. In the TUI, :connect muse-spark-1.1 resolves the provider from the catalog.

Documentation: dev.meta.ai/docs

NVIDIA API Catalog¶

export NVIDIA_API_KEY=...
superqode connect byok nvidia nvidia/nemotron-3-super-120b-a12b

NVIDIA uses its OpenAI-compatible NIM endpoint at https://integrate.api.nvidia.com/v1. Override it with NVIDIA_BASE_URL when using another compatible NVIDIA deployment. The model picker follows models.dev, so current Nemotron, Qwen, DeepSeek, and GLM routes appear without a manual SuperQode model-list update.

Documentation: NVIDIA API documentation

Poolside¶

export POOLSIDE_API_KEY=...
superqode connect byok poolside poolside/laguna-m.1

Poolside uses its first-party OpenAI-compatible endpoint at https://inference.poolside.ai/v1. Override it with POOLSIDE_BASE_URL. The hosted API route is separate from SuperQode's local Laguna GGUF support.

Documentation: Poolside platform

Moonshot AI (Kimi K3)¶

export MOONSHOT_API_KEY=...
superqode connect byok moonshot kimi-k3

SuperQode routes this provider directly to Moonshot's global OpenAI-compatible API at https://api.moonshot.ai/v1 (override with MOONSHOT_API_BASE). K3 has thinking permanently enabled; the current pay-as-you-go API accepts only reasoning_effort: max. It automatically caches stable prompt prefixes, so keep the same harness and reasoning effort within a session.

Use the maintained Kimi-family harness directly, or create an editable copy:

superqode --harness kimi-coding -p "Review this repository"
superqode harness init kimi-project --template kimi-coding --output harness.yaml

The current stable route selects moonshot/kimi-k3, its 1M context, max reasoning, native parallel tools, and a longer cache-friendly session history. Full open weights are scheduled for July 27, 2026; until compatible serving stacks publish K3 support, this preset targets Moonshot's hosted API. Use kimi-k3-coding only when the project must remain explicitly pinned to K3.

Documentation: Complete Kimi K3 provider and feature guide · Official Kimi K3 API guide

Tier 1 (First-Class Support) continued¶

Deepseek¶

export DEEPSEEK_API_KEY=sk-...
superqode connect byok deepseek deepseek-v3

Cost: Very competitive pricing

Mistral¶

export MISTRAL_API_KEY=...
superqode connect byok mistral mistral-large

xAI (Grok 4.5)¶

export XAI_API_KEY=...
superqode connect byok xai grok-4.5

Grok 4.5 supports reasoning_effort (low / medium / high, default high) and image + PDF input. Cached input is \(0.50 per million tokens, and prompts above 200K tokens are billed at a higher tier (\)4 / $12). This route uses your xAI API account and is billed separately from a consumer subscription. Grok 4.5 is not yet available in the xAI API console for EU users.

Documentation: xAI Grok 4.5 · xAI model catalog

Grok Subscription (Official CLI)¶

For an eligible local X/SuperGrok account, the Grok subscription profile has two routes on the same grok login:

• :connect grok runs Grok Build, xAI's own coding agent, over ACP. This is the default subscription route: the vendor's agent owns the loop.
• :grok api [model] runs SuperQode's own harness on the subscription. It imports the grok login session and talks to the CLI chat proxy, so core/workbench, SuperQode's tools, and memory drive Grok 4.5.

# Install the official xAI CLI if needed (macOS/Linux/WSL)
curl -fsSL https://x.ai/cli/install.sh | bash
# Windows PowerShell: irm https://x.ai/cli/install.ps1 | iex

# Sign in locally
grok login

# Grok Build (xAI's own agent) on your subscription
superqode --connect grok

Inside the TUI:

:connect grok                 # Grok Build, xAI's own agent (ACP), default
:grok api                     # SuperQode's harness on the subscription (opt-in)
:grok api grok-4.5            # ...pinned to a specific model
:grok model                   # ...or pick from a menu of subscription models
:grok models                  # list the signed-in CLI's model catalog

On SSH or another headless machine, authenticate with:

grok login --device-auth

Subscription access requires an eligible SuperGrok or X Premium+ plan; quotas and regional access are determined by xAI. For cloud or automation workloads, use XAI_API_KEY BYOK instead.

How the :grok api harness route works¶

:grok api (the SuperQode-harness opt-in) does the following:

1. Import the session token from ~/.grok/auth.json into SuperQode's local auth store (~/.superqode/auth.json, permissions 0600)
2. Connect the grok-cli provider against https://cli-chat-proxy.grok.com/v1
3. Send the headers xAI requires: X-XAI-Token-Auth, x-grok-model-override, and x-grok-client-version from your installed CLI (the proxy returns HTTP 426 when the version header is missing)

:grok api off                 # remove the imported token

Enterprise proxies are honored via GROK_CLI_CHAT_PROXY_BASE_URL.

Notes:

• CLI sessions last about 7 days; when the token expires, run grok login again, then reconnect.
• Usage counts against your subscription and model eligibility is enforced by xAI per tier. The :grok api route is intended for interactive use. For automation or benchmarking, use XAI_API_KEY BYOK.
• Most proxy models are streaming-only; SuperQode's chat path streams by default.

Model Hosts¶

Access multiple models through a single API:

OpenRouter¶

export OPENROUTER_API_KEY=sk-or-...
superqode connect byok openrouter anthropic/<anthropic-balanced-model>

• 95+ models from various providers
• Use format: provider/model-name

Documentation: openrouter.ai

Hugging Face Inference Providers¶

Hugging Face routes many open models through partner inference providers using one model id plus a provider suffix. SuperQode accepts the same route in the regular BYOK provider/model fields:

export HF_TOKEN=hf_...

# Full provider/model form
superqode connect byok huggingface zai-org/GLM-5.2:fireworks-ai

# Shorthand form, useful in config and command history
superqode connect byok hf.zai-org/GLM-5.2:fireworks-ai

SuperQode normalizes all of these forms to the Hugging Face provider:

Current GLM-5.2 routes exposed in the default config:

The :provider suffix is generic, so other Hugging Face Inference Provider routes work the same way when Hugging Face advertises them.

Documentation: huggingface.co/inference

Together AI¶

export TOGETHER_API_KEY=...
superqode connect byok together meta-llama/Llama-3.3-70B-Instruct

Groq¶

export GROQ_API_KEY=gsk-...
superqode connect byok groq llama-3.3-70b-versatile

• Very fast inference
• Free tier available

Fireworks¶

export FIREWORKS_API_KEY=...
superqode connect byok fireworks accounts/fireworks/models/llama-v3p3-70b-instruct

Configuration¶

Environment Variables¶

Configuration File¶

providers:
  anthropic:
    api_key_env: ANTHROPIC_API_KEY
    recommended_models:
      - <anthropic-model>
      - <anthropic-balanced-model>
      - <anthropic-fast-model>

  openai:
    api_key_env: OPENAI_API_KEY
    recommended_models:
      - <openai-model>
      - <openai-fast-model>

  deepseek:
    api_key_env: DEEPSEEK_API_KEY
    recommended_models:
      - deepseek-v3
      - deepseek-r1

  huggingface:
    api_key_env: HF_TOKEN
    recommended_models:
      - zai-org/GLM-5.2:fireworks-ai
      - zai-org/GLM-5.2:together
      - zai-org/GLM-5.2:novita
      - zai-org/GLM-5.2:zai-org
      - zai-org/GLM-5.2:deepinfra

model_aliases:
  glm52: hf.zai-org/GLM-5.2:fireworks-ai
  glm52-hf-together: hf.zai-org/GLM-5.2:together
  glm52-hf-novita: hf.zai-org/GLM-5.2:novita

Cost Management¶

Tracking Costs¶

superqode:
  cost_tracking:
    enabled: true
    show_after_task: true

After each task, the output includes:

Cost Summary:
  Provider: anthropic
  Model: <anthropic-balanced-model>
  Input tokens: 15,234
  Output tokens: 2,456
  Estimated cost: $0.12

Cost-Effective Strategies¶

1. Use appropriate models: Haiku/mini for simple tasks
2. Use quick mode: Shorter sessions, less tokens
3. Local fallback: Use local models for high-volume tasks

Security Best Practices¶

API Key Management¶

# Do not commit API keys
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo ".env" >> .gitignore

Rotate Keys Regularly¶

• Anthropic: console.anthropic.com
• OpenAI: platform.openai.com/api-keys

Use Project Keys¶

Where available, use project-specific API keys with limited scope.

Troubleshooting¶

"Not Configured" Error¶

[INCORRECT] Provider 'anthropic' is not configured

Solution: Set the API key environment variable.

"Invalid API Key"¶

[INCORRECT] Connection failed: Invalid API key

Solution: Verify your API key is correct and has appropriate permissions.

Rate Limiting¶

[INCORRECT] Rate limit exceeded

Solutions: - Wait and retry - Use a different provider temporarily - Upgrade your API tier

Model Not Found¶

[INCORRECT] Model 'claude-5' not found

Solution: Check available models:

superqode providers show anthropic

Provider Comparison¶

Next Steps¶

• Local Providers - Self-hosted alternatives
• ACP Agents - Coding agent integration
• Provider Commands - CLI reference