BYOK - Bring Your Own Key

BYOK (Bring Your Own Key) is the default way Kodus uses LLMs across every plan — Community, Teams, and Enterprise. You connect your own provider accounts, enable the models you want, and choose which model runs each task. You pay your provider directly, Kodus never marks up tokens, and Kodus never sees your key in plain text.

How this maps to plans

BYOK is free on Community, included on Teams ($10/active dev/month on top of your token spend), and one of two options on Enterprise (the other being a Kodus-managed API key).

How BYOK works

BYOK is provider-first: you connect a provider once, add the models you want to it, and then route those models to Kody’s tasks. The /byok screen has three tabs:

Providers

Connect providers with your key and enable models on each one. The count badge shows how many providers you’ve connected.

Routing

Choose which model runs each task — one default for everything, an optional fallback, and per-agent overrides.

Budget

Set an optional monthly spend limit across your connected models.

Who can edit this. The BYOK page is Owner-only — connecting, testing, and deleting keys requires the Owner role. Other roles (Billing Manager, Repo Admin, Contributor) can’t access /byok. See Workspace Roles.

Connect a provider

Open BYOK settings

Go to app.kodus.io/byok. On a fresh workspace you’ll see Connect your first provider.

Pick a provider

The provider grid is split in two:

Providers — first-class providers you connect with just an API key (OpenAI, Anthropic, Google AI Studio, OpenRouter, Novita…).
Custom — providers you point at your own endpoint or run an arbitrary model on: OpenAI-compatible, Anthropic-compatible, Google Vertex AI, and Amazon Bedrock. These are marked with a Custom endpoint hint.

A provider you’ve already connected shows Connected · N models.

Add a model

Picking a provider opens its Add a model form. Paste the API key once (reused for every model you add to that provider afterward), then choose the model:

If Kodus can list the provider’s models, you get a dropdown.
Otherwise (custom endpoints, self-hosted, or when platform keys aren’t configured), type the exact model ID.

Custom endpoints (OpenAI-compatible / Anthropic-compatible) also ask for a base URL first.

Tune advanced settings (optional)

Under Advanced settings: thinking/reasoning, temperature, max output tokens, max input tokens, and max concurrent requests. Defaults are sensible for most providers — see Reasoning and Temperature for the fields Kodus locks or hides per model.

Test and save

Click Test to probe the provider, or Test & save to run the test and persist on success. Add as many models to the provider as you want — the key is only pasted once.

Add another provider any time from the Providers tab. Each provider keeps its own key; enabling more models on a connected provider never re-asks for it.

Test before you save

The Test button verifies your configuration before it can break a real review. What it does depends on the provider:

Provider	What Test does
Anthropic-compatible brands (Kimi, Z.ai, DeepSeek), OpenAI-compatible, Novita	Sends a real 1-token chat request to the exact model — the same call a review makes. Catches a wrong model ID, a restricted key, and endpoint problems on the spot.
OpenAI, Anthropic, Google (Gemini/Vertex), OpenRouter, Bedrock	A cheap identity/metadata call (list-models, token exchange, or STS) — confirms the key and endpoint work.

On the chat-probe path, Test also validates the tuning you configured against the model’s own rules and returns an early, specific error instead of saving a config the model would silently ignore:

A temperature an always-thinking model won’t honor (it’s pinned to 1 — see Temperature).
Reasoning turned Off on a model that always reasons and can’t be disabled.

Because the chat providers now exercise the real model, a typo in the model ID is caught at Test time rather than at your first review — the response comes back Model not found.

Routing: which model runs each task

Once you’ve connected two or more models, the Routing tab decides which model runs what. Routing is flat: every task uses the default until you override it.

Policy

Manual · you choose is active today. Auto · Kodus optimizes is coming soon.

Defaults

Model for all tasks — the one model every task uses unless overridden.
Fallback (optional) — a different model Kody re-runs a call on once when the task’s model fails: a bad or expired key, no credit, or the provider being down (after its own retries).

Per agent

Different Kody tasks (code review, Kody Rules, chat, summaries, and more) can each run a different model — a pricier model for deep review, a cheaper one for summaries. A model that can’t do a given task is disabled in that row with a tooltip, before you can save it.

Click Save routing to persist. Reset agents to default sends every per-agent override back to the default and clears the fallback (the default model itself is kept). A read-only Per repository panel below mirrors any per-repo model overrides set in Code Review Settings.

With a single connected model, routing is skipped — every task uses that model. Connect a second model to make routing meaningful.

Choosing models

Any model your provider serves works. If you’re not sure where to start, these are solid choices for code review:

Claude Sonnet / Opus

Best balance / flagship quality. Anthropic’s adaptive extended thinking and strong cross-file analysis. Keys: console.anthropic.com.

Gemini Pro

Largest context. Google’s flagship — strongest on large PRs and monorepos. Keys: aistudio.google.com/apikey.

GPT (latest)

Fast and consistent. OpenAI’s flagship line — reliable low latency, broad knowledge. Keys: platform.openai.com/api-keys.

Kimi / GLM (coding plans)

Cheapest via subscription. Moonshot’s Kimi and Z.ai’s GLM offer flat-rate coding plans that cap monthly spend. See Connecting Kimi and GLM below.

Our default recommendation: start with Claude Sonnet for the best overall experience. If cost is the priority, a GLM Coding Plan or Kimi Code Plan gives a flat-rate subscription. Enter the exact model ID your provider documents — Kodus derives the display name from it.

Connecting Kimi (Moonshot) and GLM (Z.ai)

Moonshot and Z.ai each offer a subscription plan on a different endpoint than their pay-per-token Developer API. Each plan is a separate account with its own key — pick the base URL that matches the key you have.

Kimi (Moonshot AI)
GLM (Z.ai)

Plan	Endpoint	Keys from	Best for
Developer API	`https://api.moonshot.ai/v1` (OpenAI-compatible) or `https://api.moonshot.ai/anthropic` (Anthropic-compatible)	platform.moonshot.ai	Pay-per-token, concurrency scales with recharge tier
Kimi Code Plan	`https://api.kimi.com/coding/v1`	kimi.com/code	Subscription with a dedicated coding endpoint

Kimi Code Plan is documented at a cap of 30 concurrent requests — set maxConcurrentRequests=30. Always-reasoning Kimi variants (e.g. kimi-k2p7-code, kimi-k3) lock temperature to 1 and can’t turn reasoning off — see Temperature.

Plan	Endpoint	Keys from	Best for
Developer API	`https://api.z.ai/api/paas/v4/`	z.ai/manage-apikey	Bursty workloads, pay-per-token
Coding Plan	`https://api.z.ai/api/coding/paas/v4`	z.ai/subscribe	Predictable team volume, flat monthly fee

GLM Coding Plan keys only work on /api/coding/paas/v4. The Lite and Pro tiers are often capped at 1 concurrent request — set maxConcurrentRequests=1 and bump it (up to 30) only on the Max tier.

Supported Providers

Best for: Latest GPT models and reliable performance.Get an API key:

Visit OpenAI API Keys
Create a new key for Kodus
Add billing information

Beta. A more involved auth path than the single-key norm.

Best for: Teams already on Google Cloud that need Gemini (or Claude) under their existing GCP billing, IAM, and data-residency guarantees.How to configure:

In the connect flow, pick Google Vertex AI (under Custom).
Paste the contents of your service account JSON file into the Service Account JSON field (base64-encoded also works). Kodus extracts project_id from the JSON automatically.
Region — leave empty to use the global endpoint (recommended). Pin a region (e.g. us-east5) only when you have data-residency requirements.

The service account needs permission to call the Vertex AI prediction API in that project. Test probes the actual configured model, so an unavailable model/region fails at Test time.

Beta. A more involved auth path than the single-key norm.

Best for: Teams standardized on AWS that want models billed through their AWS account.How to configure:

In the connect flow, pick Amazon Bedrock (under Custom).
Provide a Bedrock API key (bearer token) — see How to generate a Bedrock API key.
Set the Region (e.g. us-east-1, us-west-2, eu-central-1).

Advanced: IAM user credentials instead

If your team hasn’t migrated to Bedrock API keys, expand Advanced — use IAM user credentials instead and supply a static access key ID + secret (plus a session token for STS temporary credentials). The IAM principal needs bedrock:InvokeModel.The API key takes precedence: if a bearer token is set, the IAM fields are ignored.

Best for: Specialized providers (Moonshot, Z.ai, Fireworks, Together, Groq, DeepSeek) or self-hosted endpoints.How to configure:

In the connect flow, pick OpenAI Compatible (under Custom).
Enter the base URL (e.g. https://api.moonshot.ai/v1, https://api.z.ai/api/paas/v4/, https://api.fireworks.ai/inference/v1).
Provide the key and model ID.

Model IDs are provider-specific — some use deep paths (e.g. Fireworks: accounts/fireworks/models/kimi-k2p7-code). Copy the exact ID from your provider’s dashboard; Test sends a real request, so a wrong ID fails immediately.

Z.ai (GLM) guide

Full Z.ai setup with Coding Plan details.

Moonshot (Kimi) guide

Kimi + Kimi Code Plan setup.

Fireworks AI

Fireworks-specific setup.

Together AI

Together AI setup.

Best for: Endpoints that speak the Anthropic Messages API rather than the OpenAI one — including coding-plan endpoints such as Kimi’s.How to configure:

In the connect flow, pick Anthropic-compatible (under Custom).
Enter the base URL, the key, and the model ID.

Paste the base URL in whichever shape your provider documents — with or without a trailing /v1 (e.g. https://api.kimi.com/coding or https://api.kimi.com/coding/v1). Kodus normalizes it internally, because the two Anthropic SDK paths disagree on where /v1 belongs. For a known brand, a key-only connect resolves the endpoint automatically.

Reasoning / Extended Thinking

The Add a model form exposes a Thinking toggle (Off / Low / Medium / High / Custom) under Advanced settings. The available options mirror what the model can actually do:

A model that can’t reason is locked to Off with a note.
A model that only reasons at certain levels (e.g. GPT-5’s medium/high) disables the invalid ones.
A reasoning-by-default model gets Medium as a sensible starting point.

Preset levels

When you pick Low / Medium / High, Kodus translates the level to each provider’s native format automatically:

Provider	How “medium” maps
Anthropic (Claude adaptive)	`thinking: { type: "adaptive" }` + `effort: "medium"`
Google (Gemini)	`thinkingConfig: { thinkingLevel: "medium" }`
OpenAI (GPT-5 / o-series)	`reasoningEffort: "medium"`
OpenRouter	`reasoning: { effort: "medium" }`
OpenAI-compatible / Anthropic-compatible (Kimi, GLM, DeepSeek)	`thinking: { type: "enabled" }` — binary on/off, level ignored

Kimi and GLM currently expose reasoning as a single on/off flag. Picking Low, Medium, or High all emit the same payload (thinking enabled). Always-reasoning variants (Kimi k2p7-code/k3, GLM-5.3) reason unconditionally — they can’t be turned Off, and the form disables that option.

Custom JSON override

Picking Custom in the Thinking toggle reveals a JSON textarea. Paste the provider options directly — Kodus auto-wraps them under the active provider’s namespace. You don’t need to know the Vercel AI SDK routing rules. Use this when:

You need a specific budgetTokens value for Claude (instead of the preset effort mapping)
You want to enable/disable thinking on a per-model basis for OpenAI-compatible providers
You want fields beyond reasoning — caching, service tier, safety settings, user tagging, etc. The override is merged into providerOptions, so any adapter field passes through
The provider ships a new field Kodus hasn’t wrapped yet

Examples (paste directly — no namespace needed)

Anthropic
Google Gemini
OpenAI
OpenRouter
OpenAI-compatible (Kimi, GLM, etc.)

Override Claude’s thinking budget to exactly 20,000 tokens:

{
  "thinking": { "type": "enabled", "budgetTokens": 20000 }
}

Enable prompt caching (non-reasoning example):

{
  "cacheControl": { "type": "ephemeral" }
}

Explicit thinking budget (Gemini 2.5) or level (Gemini 3+):

{
  "thinkingConfig": { "thinkingBudget": 16000 }
}

Adjust safety settings:

{
  "safetySettings": [
    { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE" }
  ]
}

Reasoning with OpenAI-specific fields:

{
  "reasoningEffort": "high",
  "serviceTier": "flex",
  "store": false,
  "user": "kodus-review"
}

Force reasoning + ignore a specific upstream:

{
  "reasoning": { "effort": "high" },
  "ignore": ["deepinfra"]
}

Enable thinking with a budget hint:

{
  "thinking": { "type": "enabled", "budget_tokens": 25000 }
}

Explicitly disable thinking (only on a model that supports it):

{
  "thinking": { "type": "disabled" }
}

Fields the upstream provider doesn’t recognize (e.g. budget_tokens on a server that ignores it) are silently dropped. Check the provider’s docs to confirm what they accept.

Going manual with namespaces (power users)

If your JSON already starts with a known namespace key at the top level — any key from the mapping table below — Kodus leaves it untouched. Useful if you want to mix multiple provider namespaces or be explicit:

{
  "openrouter": {
    "reasoning": { "effort": "high" },
    "provider": { "order": ["moonshot"], "allow_fallbacks": false }
  }
}

Under the hood, these are the namespace mappings Kodus uses:

BYOK provider	Namespace key
`anthropic` / `anthropic_compatible`	`anthropic`
`google_gemini`	`google`
`google_vertex`	`google` for Gemini, `anthropic` for Claude on Vertex
`openai`	`openai`
`openai_compatible`	`openaiCompatible`
`azure`	`azure`
`amazon_bedrock`	`amazonBedrock` (also accepts `bedrock`)
`novita`	`novita`
`open_router`	`openrouter`

Gotchas

Valid JSON only. Missing commas or trailing commas break the parse and Kodus ignores the override.
Precedence: the JSON override fully replaces the effort-preset’s namespace block — if you override anthropic.thinking but forget anthropic.effort, that field won’t be sent. OpenRouter routing (Pin providers / Allow fallbacks) is the one exception: it deep-merges with your override under openrouter.
Unknown provider = no wrap. If your BYOK provider isn’t in the namespace table above, Kodus passes the JSON through as-is.

Temperature

Temperature lives under Advanced settings, and the field adapts to the model’s rules — set by the provider, not guessed by the form:

Model	Temperature field
Most models	Editable (0 = deterministic, 2 = creative).
Always-reasoning Anthropic-protocol models (Kimi `k2p7-code`/`k3`, GLM-5.3)	Locked to `1`. The protocol pins temperature to 1 while thinking, so 1 is the only sound value — the field shows a lock and Kodus sends `1` regardless of what was stored.
Claude 4.7+ and OpenAI GPT-5 / o-series	Hidden. These models removed temperature and reject any request that sets it — steer them with the thinking level instead.

On the chat-probe providers, Test validates the temperature you set against these rules and returns an error before saving — so you never persist a value the model won’t honor.

Pinning OpenRouter providers

OpenRouter is a router — when you request a model (e.g. moonshotai/kimi-k2), it forwards the call to one of several upstream providers (Moonshot direct, Together, Groq, Fireworks, Novita…). Each call can land on a different backend. That’s convenient, but it introduces silent variance:

Quality drift — upstreams run different precisions (FP8, INT4, full) and give subtly different outputs for identical prompts
Tool-calling inconsistency — some backends don’t support function calling the same way, leading to malformed tool use
Reasoning format variance — one upstream honors reasoning_effort, another only thinking.enabled, another ignores both
Latency swings — p50 can jump from 800ms to 4s between calls as routing changes
Rate-limit surprises — you hit quota on a backend you didn’t explicitly choose

How to pin

When your BYOK provider is OpenRouter, the Advanced settings panel shows an OpenRouter routing section with two fields:

Pin providers (in order) — comma-separated list of upstream names (e.g. moonshot, together). OpenRouter tries them in order and uses the first available.
Allow fallbacks — when off, requests hard-fail if none of the pinned providers are available. When on (default), OpenRouter can fall back to any other upstream that serves the model.

For a stable setup, pin a single provider and turn off fallbacks (Pin: moonshot, Allow fallbacks: off). Requests will always hit the same upstream or fail loudly — no silent quality changes. The tradeoff is zero resilience if that one upstream goes down; pair it with a different Routing Fallback (e.g. Anthropic) to absorb outages.

Upstream names must match OpenRouter’s catalog. Check the provider tags on openrouter.ai/docs/features/provider-routing — common values include moonshot, together, groq, fireworks, novita.

Under the hood, Kodus emits this into the Vercel AI SDK call:

{
  "openrouter": {
    "provider": {
      "order": ["moonshot", "together"],
      "allow_fallbacks": false
    }
  }
}

Advanced: raw JSON override

If you need fields beyond order and allow_fallbacks (e.g. ignore, data_collection, require_parameters), switch Thinking to Custom in Advanced settings and paste the full routing payload — it’s merged into providerOptions alongside any reasoning config:

{
  "openrouter": {
    "provider": {
      "order": ["moonshot"],
      "allow_fallbacks": false,
      "ignore": ["deepinfra"],
      "data_collection": "deny"
    },
    "reasoning": { "effort": "medium" }
  }
}

Concurrency and rate limits

The maxConcurrentRequests field (under Advanced settings) caps how many inflight requests Kodus sends to your provider in parallel. Most of the time, the default is fine — but subscription plans with strict concurrency caps need it set explicitly.

Values to set

Provider / plan	Value	Why
GLM Coding Plan (Lite/Pro)	`1`	Subscription allows only one in-flight request. Going higher triggers 429s.
GLM Coding Plan (Max)	up to `30`	Max allows up to 30 concurrent — raise it here to use the full budget.
Kimi Code Plan	`30`	Moonshot’s documented cap on the coding endpoint.
GLM Developer API	(empty)	Limits scale per key; no sensible global default.
Kimi Developer API	(empty)	Scales with your recharge tier (Tier 1 ≈ 50, Tier 5 ≈ 1000).
Anthropic / OpenAI / Google / OpenRouter	(empty)	Providers enforce their own TPM/RPM; Kodus doesn’t cap.

When to tune it

Raise it

You have a high-tier recharge on Moonshot/OpenRouter and want higher throughput on big PRs
You bumped your GLM Coding Plan to Max and want to use the full 30-concurrent budget
Reviews feel serialized on multi-file PRs and you’re not seeing 429s

Lower it

You see 429 or Too much concurrency errors in review logs
Your provider warns about rate limits on the dashboard
You want to conserve Coding Plan window (5h/weekly) across more PRs

Concurrency vs. RPM vs. TPM. maxConcurrentRequests only caps parallel inflight requests. Many providers also enforce separate RPM (requests per minute) and TPM (tokens per minute) limits. If you’re hitting RPM/TPM while concurrency looks fine, the fix is usually to upgrade your tier or spread load across time — not to change maxConcurrentRequests.

Fallback interaction. When a task’s model hits a 429 and Kody fails over to the Routing Fallback, the Fallback’s own maxConcurrentRequests applies. Setting a generous Fallback on a different provider is a good way to absorb bursts when your main model is on a tight subscription.

Best Practices

Security

Dedicated Keys

Create separate API keys for Kodus. Makes usage auditing and key rotation easier.

Regular Rotation

Rotate keys periodically and update them in BYOK settings.

Monitor Usage

Check your provider dashboards for unusual patterns.

Secure Storage

Never commit keys to repositories. Kodus stores them encrypted at rest and in transit.

Routing strategy

Use a different provider for your default and fallback (e.g. Anthropic default, Google fallback). Protects against provider-specific outages.
Subscriptions with tight concurrency limits (GLM Coding Plan Lite/Pro, Kimi Code Plan) make poor solo configurations — pair them with a pay-per-token fallback so bursty PRs don’t starve.
Route the heavy tasks (deep code review) to your strongest model and the light ones (summaries, chat) to a cheaper one under Per agent.

Troubleshooting

'Invalid API key' when clicking Test

Copy the key without extra spaces, quotes, or trailing newlines.
Confirm billing is enabled and the account has credits.
For GLM Coding Plan / Kimi Code Plan keys, make sure the base URL matches the plan — subscription keys don’t work on the Developer API endpoint and vice versa.

'Model not found' when clicking Test

For the chat-probe providers (Anthropic-compatible, OpenAI-compatible, Novita), Test sends a real request to the model, so a wrong or misspelled model ID fails here — this is expected and better than failing at review time.
Copy the exact model ID from the provider’s dashboard. Some providers use deep paths (e.g. Fireworks accounts/fireworks/models/kimi-k2p7-code) or spell versions differently (k2p7 vs k2.7).

'Endpoint not found' when clicking Test

Verify the base URL matches the provider exactly (trailing slash matters for some).
For OpenAI-compatible providers, the endpoint is usually {baseURL}/chat/completions (Kodus adds the path).

Test rejects the temperature or reasoning I set

Some models pin temperature or always reason (Kimi k2p7-code/k3, GLM-5.3; Claude 4.7+/GPT-5 remove temperature entirely). Test validates your tuning against the model’s rules and returns a specific message — follow it (leave temperature unset or use the required value; don’t turn reasoning Off on an always-reasoning model). See Temperature.

'Rate limited' or 'Too much concurrency'

Lower Max concurrent requests in Advanced settings.
On GLM Coding Plan Lite/Pro, stay at 1 concurrent. Upgrade to Max (30 concurrent) if you need more throughput.
On Kimi Code Plan, the documented cap is 30 concurrent.

Self-hosted env vars not showing

If Kodus is configured via .env (self-hosted Fixed Mode), the BYOK screen shows a blue info banner with the active provider/model — the key is never displayed for security.
Connecting a model and saving overrides the .env configuration.

High or unexpected costs

Reasoning adds tokens. If cost is spiking, lower Thinking from Medium to Low, or route heavy tasks to a cheaper model under Per agent.
Check your provider dashboard for the per-model breakdown, and set a cap under the Budget tab.

Frequently Asked Questions

Can I switch providers anytime?

Yes. The change takes effect for the next review — no redeploy required.

What happens if my API key runs out of credits?

Reviews automatically switch to the Routing Fallback if one is configured. Without a Fallback, the review fails and returns an error. Always configure a Fallback.

How does the default / fallback system work?

Every task uses the default model unless you override it per agent in Routing. If a task’s model fails (rate limit, 5xx, timeout, bad key), Kody retries once on the Fallback. You pay only for the provider that actually processed the call.

Can different tasks use different models?

Yes — that’s what Routing → Per agent is for. Route deep code review to a strong model and summaries or chat to a cheaper one. You need at least two connected models for routing to be meaningful.

Do you store our API keys securely?

Yes. Keys are encrypted at rest and in transit and never logged in plain text. The BYOK status endpoint never returns the raw key.

Can I use a self-hosted LLM (e.g. Ollama, vLLM)?

Yes — via the OpenAI Compatible provider (under Custom). Enter your endpoint’s base URL, the model ID it exposes, and a placeholder API key (most self-hosted runtimes ignore the key header but still require one).

How this maps to plans

​How BYOK works

Providers

Routing

Budget

​Connect a provider

​Test before you save

​Routing: which model runs each task

​Choosing models

Claude Sonnet / Opus

Gemini Pro

GPT (latest)

Kimi / GLM (coding plans)

​Connecting Kimi (Moonshot) and GLM (Z.ai)

​Supported Providers

Novita Setup Guide

Z.ai (GLM) guide

Moonshot (Kimi) guide

Fireworks AI

Together AI

​Reasoning / Extended Thinking

​Preset levels

​Custom JSON override

​Examples (paste directly — no namespace needed)

​Going manual with namespaces (power users)

​Gotchas

​Temperature

​Pinning OpenRouter providers

​How to pin

​Advanced: raw JSON override

​Concurrency and rate limits

​Values to set

​When to tune it

Raise it

Lower it

​Best Practices

​Security

Dedicated Keys

Regular Rotation

Monitor Usage

Secure Storage

​Routing strategy

​Troubleshooting

​Frequently Asked Questions

How BYOK works

Connect a provider

Test before you save

Routing: which model runs each task

Choosing models

Connecting Kimi (Moonshot) and GLM (Z.ai)

Supported Providers

Reasoning / Extended Thinking

Preset levels

Custom JSON override

Examples (paste directly — no namespace needed)

Going manual with namespaces (power users)

Gotchas

Temperature

Pinning OpenRouter providers

How to pin

Advanced: raw JSON override

Concurrency and rate limits

Values to set

When to tune it

Best Practices

Security

Routing strategy

Troubleshooting

Frequently Asked Questions