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.
Model choice is per-agent
Section titled “Model choice is per-agent”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: reviewerBackends
Section titled “Backends”| 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 ID format
Section titled “Model ID format”Model IDs are written the way your provider names them.
OpenRouter — the full provider-prefixed ID:
anthropic/claude-sonnet-5.5anthropic/claude-opus-5.5anthropic/claude-haiku-5.5Anthropic direct — the bare ID:
claude-sonnet-5-5claude-opus-5-5claude-haiku-5-5OpenAI-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.
Connecting a key
Section titled “Connecting a key”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.
- Pick the key provider: OpenRouter, Anthropic direct, or OpenAI-compatible.
- 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 anhttps://URL; empty meanshttps://api.openai.com/v1. - 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.
Key kind and backend compatibility
Section titled “Key kind and backend compatibility”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.
Switching models
Section titled “Switching models”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.