Skip to content

Models and BYOK

Mate is bring-your-own-key (BYOK). You connect your own LLM provider key, and jobs consume tokens directly against your provider account. Mate does not mark up token costs and does not bill for LLM usage. Mate’s billing covers compute capacity (concurrent agent slots) only.

Claude subscription (OAuth) tokens are not supported: claude-code runs on an Anthropic or OpenRouter API key only.

You own the provider relationship, so cost control (budgets, rate limits, spend caps) is set up with your provider.

The backend: and model: fields are set on each agent individually, so different triggers can use different models:

agents:
triage:
backend: claude-code
model: anthropic/claude-haiku-5.5 # fast, cheap — for triage
system_prompt: |
Triage this issue: add a priority label and a one-sentence summary.
permissions: [read, comment, update_issue]
reviewer:
backend: claude-code
model: anthropic/claude-opus-5.5 # strong — for code review
system_prompt: |
You are a senior code reviewer. Be thorough.
permissions: [read, comment]
triggers:
- on: issue
assigned: true
agent: triage
- on: merge_request
review_requested: true
agent: reviewer
Backend Talks to
claude-code Anthropic API, or OpenRouter’s Anthropic-compatible endpoint
codex OpenAI Responses API (OpenAI, OpenRouter, or a compatible endpoint)
omp OpenAI chat completions (any OpenAI-compatible endpoint) or Anthropic
opencode OpenAI chat completions (any OpenAI-compatible endpoint) or Anthropic

Any other backend id is rejected when the config is loaded.

Model IDs are written the way your provider names them.

OpenRouter — the full provider-prefixed ID:

anthropic/claude-sonnet-5.5
anthropic/claude-opus-5.5
anthropic/claude-haiku-5.5

Anthropic direct — the bare ID:

claude-sonnet-5-5
claude-opus-5-5
claude-haiku-5-5

OpenAI-compatible endpoints — whatever that endpoint calls the model, for example mistral-large-latest.

Mate is provider-neutral and never validates a model ID: not when you save the config and not when an event arrives. The provider rejects an unknown ID when the job runs, and the error shows in the job’s status note on GitLab. Copy the ID exactly as your provider documents it.

Add your LLM key in the console, either from the Add your LLM key item of the setup checklist or later under Settings → LLM key. There is one LLM key, and so one AI endpoint, per workspace.

  1. Pick the key provider: OpenRouter, Anthropic direct, or OpenAI-compatible.
  2. For OpenAI-compatible keys, optionally enter a Base URL (the root of an OpenAI-compatible API, for example https://api.mistral.ai/v1). It must be an https:// URL; empty means https://api.openai.com/v1.
  3. Paste the key (20 to 500 characters) and click Save key. To rotate it, click Replace key and submit a new one.

Mate checks the key against the provider before saving it. A rejected key is not stored. If the provider cannot be reached, the key is saved unverified and the console says so. The key is stored encrypted and is write-only: the console never shows it again.

The key never enters the agent container. A sidecar next to the job holds it and swaps a per-job placeholder for the real key on requests to your provider.

The workspace key is injected for every agent that carries no credential of its own. Which backends a key can run depends on its kind:

Key kind claude-code codex omp / opencode
Anthropic direct works not compatible works
OpenRouter works works works
OpenAI-compatible not compatible works (provider needs the Responses API) works

If the pair is incompatible, the job fails before anything starts and Mate posts the reason on the GitLab note, for example this workspace's LLM key (anthropic) can't run backend "codex".

The check is skipped when the agent, or the repo’s .mate.yml, supplies its own credential for that backend. An agent that does this owns its whole LLM configuration; see .mate.yml reference.

Pick the backend your provider supports: codex calls the Responses API, while omp and opencode call chat completions, which is what providers without a Responses API (such as Mistral) offer.

Update the model: field in your agent definition (via the console or by committing a change to .mate.yml). The change takes effect on the next job dispatch — in-flight jobs are not affected.