What BYOK actually changes

"Bring your own key" is a billing and boundary decision before it is a model decision. In CodeOtter the language-model provider is one installation-level setting under Settings → System → Model provider. You pick a row, paste a key, and from then on the vendor that bills your reviews is the vendor you chose — not CodeOtter, which has no per-seat billing and no per-review billing at all.

What the key does not change is the shape of the answer. The six calibrated 0–100 gauges (Quality, Blast Radius, Risk, Tests, Readability, PR Hygiene) and the nine binary merge gates (Title, Description, Security, Complexity, Tests, Docs, Scope, Guidelines, Issue Requirements) come from System 1 — the deterministic engine exposed at POST /v1/systemone. The provider you pick writes the prose: the summary, the findings, the file walkthrough and the committable suggestion blocks.

That split is the whole design. Your provider is a writing preference; the merge gate is not a function of it.

If you only want the mechanics of pointing the app at your key, docs.codeotter.io/docs/byok-config is the how-to. This post is the layer underneath it: what the registry actually contains, in what order the values are resolved, and what a review hands to the provider when it gets there.

The registry: one map, not a pile of branches

Provider configuration lives in a single object in core/server.mjs. Every provider is one row, and every row answers the same six questions: what it is called, which API shape it speaks, which base URL it uses, which models ship with it, which env var holds the key, and where do you go to get that key.

Here is the shape of a row, verbatim from the registry:

// core/server.mjs — one row of the PROVIDERS map
openai: {
  label: "OpenAI (ChatGPT)",
  api: "openai",
  baseUrl: "https://api.openai.com/v1",
  models: ["gpt-5", "gpt-5-mini", "gpt-4.1"],
  keyEnv: "OPENAI_API_KEY",
  keyUrl: "https://platform.openai.com/api-keys",
},

Two fields do the interesting work. api selects the wire format — "anthropic" for the Messages API, "openai" for the Chat Completions shape that every other hosted provider also speaks, which is why MiniMax and OpenRouter need no adapter code at all. And noKey: true marks the rows that must never carry a credential, which is how the local Ollama row stays local.

The full matrix, as shipped:

ProviderRegistry keyAPI shapeBase URLKey env varShipped models
Claudeanthropic/v1/messageshttps://api.anthropic.comANTHROPIC_API_KEYclaude-opus-5-5, claude-sonnet-5-5, claude-haiku-4-5
OpenAIopenai/chat/completionshttps://api.openai.com/v1OPENAI_API_KEYgpt-5, gpt-5-mini, gpt-4.1
MiniMaxminimax/chat/completionshttps://api.minimax.io/v1MINIMAX_API_KEYMiniMax-M3, MiniMax-M2.5
OpenRouteropenrouter/chat/completionshttps://openrouter.ai/api/v1OPENROUTER_API_KEYClaude, OpenAI, Qwen and DeepSeek model ids, plus more the router serves
Ollama (local)ollama/chat/completionshttp://localhost:11434/v1none (noKey: true)qwen2.5-coder:latest, deepseek-coder-v2:latest, llama3.1:latest
Custom OpenAI-compatiblecustom/chat/completionsyoursyoursyours

Six rows. Four hosted keys. One local endpoint that needs no key at all.

The local GGUF catalog is a separate axis from this table: the six rows above are hand-written in PROVIDERS, while the catalog in core/models.json contributes its own local_* rows at startup (Qwen2.5-Coder 1.5B and 7B, Microsoft CodeReviewer), served by the llama and codereviewer runtimes. /blog/how-codeotter-runs-five-open-weight-models-locally/ walks that catalog and the download flow in full.

Two engines, two keys

The mistake most BYOK write-ups make is treating "the model" as one thing. CodeOtter has two, configured separately.

System 2 is the language model — the provider in the table above. It is resolved by llmConfig() and it produces the narrative review.

System 1 is the deterministic rubric engine. It is resolved by its own function, s1Config(), against its own registry of System One providers, and it is the thing that answers POST /v1/systemone with the 6 rubric scores and the 9 merge gates. It can be a local sidecar — the Laya typed-decisions runtime and the Kev checkpoints ship with CodeOtter and run on your hardware — or a hosted endpoint that speaks the same typed contract.

The two never have to live in the same place, and that is the point. The README states it as a rule:

codeotter review, pr, ci and the MCP server run the installation's configured language and System One models through core/server.mjs. A configured System One model owns every score and gate; --provider/--model flags override the language model only.

So: Claude for the prose, a local sidecar for the gates, and the only AI requests that leave your machine are the ones to Claude. Or the whole thing local, and no diff goes to a hosted AI provider. The dual-engine deep-dive covers why the split exists; this is the configuration consequence of it.

Which key wins: the resolution chain

llmConfig() is the function that answers "what am I actually calling right now?", and it is short enough to read in one sitting:

// core/server.mjs — llmConfig()
async function llmConfig() {
  const saved = (await store.getSetting("llm")) || {};
  const provider = saved.provider || ENV_DEFAULTS.provider;
  const p = PROVIDERS[provider] || PROVIDERS.custom;
  const isEnv = provider === ENV_DEFAULTS.provider;
  if (p.local) return { provider, api: p.local.api || "openai", local: p.local, baseUrl: "", model: p.local.modelId, apiKey: "", contextChars: p.local.contextChars, enabled: modelReady(p.local), source: "settings" };
  return {
    provider,
    api: p.api,
    baseUrl: saved.baseUrl || (isEnv ? ENV_DEFAULTS.baseUrl : p.baseUrl),
    model: saved.model || (isEnv ? ENV_DEFAULTS.model : p.models[0] || ""),
    apiKey: saved.apiKey || (p.keyEnv && process.env[p.keyEnv]) || (isEnv ? ENV_DEFAULTS.apiKey : ""),
    source: saved.provider ? "settings" : "env",
  };
}

Read the three || chains and you have the whole precedence rule:

  1. What you saved in Settings wins. saved.provider, saved.baseUrl, saved.model and saved.apiKey are the values from the Settings screen.
  2. Then the provider's own env var. If the row's keyEnv is set in the environment, that key is used — ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for OpenAI, MINIMAX_API_KEY for MiniMax, OPENROUTER_API_KEY for OpenRouter. This is why a Docker deployment with keys in .env boots working with no further setup.
  3. Then the registry default. The base URL and the first model id in the row's models array.

The source field is the receipt: "settings" means your saved config is in play, "env" means nothing was saved and the environment is driving. When a review behaves differently from what you expected, that string is the first thing to look at.

The environment defaults themselves are one ternary:

// core/server.mjs — ENV_DEFAULTS
const ENV_DEFAULTS = process.env.LLM_BASE_URL
  ? { provider: "custom", baseUrl: process.env.LLM_BASE_URL, model: process.env.LLM_MODEL || "", apiKey: process.env.LLM_API_KEY || "" }
  : { provider: "minimax", baseUrl: PROVIDERS.minimax.baseUrl, model: process.env.LLM_MODEL || "MiniMax-M3", apiKey: process.env.LLM_API_KEY || "" };

A custom base URL in the environment pins the installation to the custom row — that is the supported way to point the whole app at an internal AI gateway, vLLM or LiteLLM proxy without touching the registry. Without it, the environment default provider is MiniMax with MiniMax-M3 as the model id.

The CLI carries its own resolver

The CLI is not a second implementation with its own idea of the world. tui/codeotter.mjs carries its own resolver so that a standalone codeotter review works without a running installation, and it resolves the registry's provider keys to the same base URLs. It also accepts other OpenAI-compatible endpoint keys, but the six registry rows are the ones the Settings screen offers:

// tui/codeotter.mjs — trimmed: one branch per provider key in between
function resolveProvider(flags = {}) {
  if (flags.provider) return flags.provider;
  if (flags.model?.includes("claude") || process.env.ANTHROPIC_API_KEY) return "anthropic";
  // … one branch per provider key …
  return "ollama";
}

The precedence is the same shape as the server's: an explicit --provider wins, then a model-name hint, then whichever provider key the environment holds, and finally a local endpoint. Four flags do the overriding:

FlagOverrides
--providerThe provider key — the registry's anthropic, openai, minimax, openrouter, ollama, custom
--modelThe model id sent to that provider
--base-urlThe base URL, for gateways and proxies
--keyThe key, for a provider whose env var is not set

The catch worth knowing: when the CLI talks to a running installation it runs that installation's configured engines through core/server.mjs — so the System One model that owns your scores and gates is the installation's, and --provider / --model only move the language model. The same rule is what /blog/adding-codeotter-to-your-ci-pipeline/ relies on when it runs as a merge blocker in CI.

What actually leaves the box

This is the part a security review should care about, and it is worth being precise about, because "the diff goes to the provider" is true but incomplete.

The review prompt is built in one function, prompt() in core/server.mjs. Here is the full inventory of what goes into it:

  • PR metadata — number, title, author login, base and head refs, head SHA, changed-file count, additions and deletions.
  • The PR description, truncated to 3,000 characters.
  • Outside-diff call-graph context — the callers of the symbols your diff exports, found outside the diff.
  • The incremental delta block — what changed since the last review.
  • Linked issues — number, repository, state, title, labels and up to 1,200 characters of each issue body, because the Issue Requirements gate asks whether the diff fulfils them.
  • Repository team learnings — the patterns your team has dismissed, so the model stops re-flagging them.
  • Fixes the team accepted earlier, the last ten.
  • Git commit history, truncated to 4,000 characters.
  • Your review guidelines — the text of AGENTS.md or CLAUDE.md, auto-detected at the repo root and injected in full. This is the /blog/agents-md-as-a-merge-gate/ mechanism, and the guidelines text is part of the prompt.
  • The diff, compressed to a budget of 90,000 characters (REVIEW_DEFAULTS.diffChars), highest-priority files first when the diff is over budget.

Then there is the request shape, and it is two shapes:

// Claude — the Messages API
const res = await fetch(`${base}/v1/messages`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": c.apiKey, "anthropic-version": "2023-06-01" },
  body: JSON.stringify({ model: c.model, max_tokens: 16000, ...(/^claude-(opus|sonnet|fable)-5/.test(c.model) ? { output_config: { effort: "high" } } : {}), messages: [{ role: "user", content: prompt }] }),
  signal: withAbort(c.signal, 600000),
});

// everything else — the OpenAI-compatible Chat Completions shape
const res = await fetch(`${base}/chat/completions`, {
  method: "POST",
  headers: { "content-type": "application/json", ...(c.apiKey ? { authorization: `Bearer ${c.apiKey}` } : {}) },
  body: JSON.stringify({ model: c.model, temperature: c.temperature ?? 0.2, messages: [{ role: "user", content: prompt }] }),
  signal: withAbort(c.signal, c.local ? 900000 : 180000),
});

And System 1, which is a completely separate request with a completely separate provider:

// core/server.mjs — askSystemOne()
const res = await fetch(`${base}/v1/systemone`, {
  method: "POST",
  headers: { "content-type": "application/json", accept: "application/json", ...(c.apiKey ? { authorization: `Bearer ${c.apiKey}` } : {}) },
  body: JSON.stringify({ model: c.model, state, questions }),
});

Two things fall out of that inventory that are worth stating plainly.

A review is two provider calls, not one. The first call produces candidate findings; the second is the self-check pass, where the same model scores each finding from 0 to 10 against the diff and findings below the configured threshold (default 5) are dropped. Your provider bill for one review is roughly two calls' worth of tokens.

The guidelines travel with the diff. If your AGENTS.md contains internal conventions, service names or — heaven forbid — a credential pasted by accident, that text goes to the provider along with the diff. This is the honest cost of a hosted BYOK provider, and it is exactly what the local configuration removes: with the models running on your hardware, the model request never leaves the machine.

Timeouts follow the same split, with one exception: a Claude call is given 600 seconds, a hosted OpenAI-compatible call 180 seconds and a local one 900 seconds; a hosted System One call is given 60 seconds and a local one 300 seconds. CodeOtter ships zero telemetry. The only AI requests that leave your network are the ones to the provider you configured. CodeOtter also talks to your code host: it reads the pull request, its linked issues and your AGENTS.md or CLAUDE.md from it, and can post the review, inline suggestions and a commit status back. And the web UI's update notice checks GitHub Releases at most every six hours (CODEOTTER_UPDATE_CHECK=0 turns that off).

How the pieces connect

Note what is not on that diagram: no CodeOtter server in the middle of your code's journey, and no telemetry collector. The installation resolves a provider, the provider answers, and the answer comes back.

Choosing a provider

There is no price list here, deliberately. A per-review cost depends on your diff size, your provider's current rates and how many findings the self-check pass has to chew through — a number we publish would be a number that is wrong within a month. What you can reason about is structural:

  • If you need the merge gate to be reproducible, keep System 1 local. The gates are the deterministic engine's output; pointing it at a hosted endpoint makes the gate's provider a dependency of your merge policy. The local sidecar option (Laya typed-decisions, Kev 0.8B, Kev 4B) keeps it on your hardware.
  • If code must not leave your network, the answer is the local configuration, not the hosted one. A BYOK key keeps the billing relationship yours; it does not keep the diff yours. Local models are the only configuration where no diff goes to a hosted AI provider.
  • If you already pay for one of the four, use it. OpenRouter is the multi-vendor row: one key reaches Claude-, OpenAI-, Qwen- and DeepSeek-class models, so you can change the model without changing credentials.
  • If your provider speaks the OpenAI shape, you do not need a release. The custom row takes a base URL, a model id and a key. docs.codeotter.io/docs/byok-config has the exact fields.
  • If you run an internal gateway, use LLM_BASE_URL. Setting it in the environment pins the installation to the custom row with LLM_MODEL and LLM_API_KEY, so every repo inherits it without anyone touching the Settings screen.

Where the keys live, and how to rotate one

Keys are entered in the Settings screen and stored with the rest of your installation's configuration — the same PocketBase-backed store that holds your accounts — never in a file in the repo and never in a commit. Next to the model row there is a Test button: it sends a Reply with the single word OK. prompt to the configured provider and reports the round-trip time, so a typo surfaces at the point of entry instead of at the first review. Saving the key sends no prompt and no code, though the Settings screen does use it to ask the provider for its model list. The test is a separate, explicit action that sends a prompt. docs.codeotter.io/docs/byok-config covers the storage details and the rotation flow.

The other thing worth knowing is that keys can arrive from two directions at once: the environment and the Settings screen. The source field in llmConfig() tells you which one is currently in effect, so when a rotation does not seem to take, check that field before you check the dashboard.

Ship it

CodeOtter is a self-hosted AI pull request reviewer: six calibrated 0–100 gauges, nine binary merge gates, a deterministic System 1 engine at POST /v1/systemone, and a narrative reviewer you point at your own key. It is open source under the GNU Affero General Public License v3.0 (AGPL-3.0) — free to self-host, modify and redistribute; a modified version offered as a network service must publish its source.

The fastest path to a running instance is docs.codeotter.io/docs/docker-quickstart; the local-model path is docs.codeotter.io/docs/local-gguf-sidecar; and if you want the wire format for an agent rather than a human, the MCP server deep-dive shows the same engines behind two stdio tools.

Pick the row, paste the key, and read source before you trust it.