Tenant configuration

The tenant configuration is the YAML document you edit in the Config tab of the Mate console. It applies to every repository in your tenant. Repositories may overlay it with a .mate.yml file; the tenant config is always the hard ceiling for what any repository can do.

The tenant config and .mate.yml share the same schema. This page is the canonical reference for all shared fields. The .mate.yml reference documents the repo-only additions (system_prompt_append, extends restrictions, the trigger when: filter).

Note

The console config editor validates your YAML before saving it. Errors are shown with line and column positions. The console validates structure and references; a small number of value checks (such as version and model IDs) only run when the config is loaded at dispatch time, so a config that saves cleanly may still fail those checks at runtime.

Top-level structure

version: 1                    # required; must be 1
deny: [<authority>, ...]      # optional, tenant-wide blanket deny
agents: { ... }               # map of agent-name → definition
triggers: [ ... ]             # ordered list; first match fires
policies: { ... }             # optional

Unknown top-level keys are a validation error. bots: (bot registration) is managed through the Bots tab in the console, not through this YAML.

deny

Optional list of authorities to remove from every agent’s effective permission set across the entire tenant, for every trigger. An authority listed here cannot be granted by any agent or trigger configuration. Typical uses: compliance mandates, incident response, or a per-tenant kill switch.

deny:
  - push_branch
  - merge

Unknown authority strings in deny: are a validation error.

Agents

The agents: block is a map from agent name to agent definition. The name is a free-form string used to reference the agent from a trigger’s agent: field.

agents:
  reviewer:
    description: "Reviews MRs for correctness and style"
    backend: claude-code
    model: anthropic/claude-sonnet-4-6
    system_prompt: |
      You are a senior code reviewer. Focus on correctness,
      readability, and obvious security issues. Be concise.
    permissions: [read, comment]
    timeout: 30m

Agent fields

Field	Required	Type	Description
backend	yes	string	LLM CLI adapter. Use claude-code — it is the only functional backend. copilot and aider are accepted by validation but currently run the claude-code adapter regardless.
model	yes	string	OpenRouter model ID, e.g. anthropic/claude-opus-4-7.
system_prompt	yes*	string	The agent’s system prompt, inline only. Mutually exclusive with system_prompt_append.
permissions	yes	list of authorities	Non-empty list of authority values.
description	no	string	Free-text note for your own reference (not currently displayed in the console).
image	no	string	Docker image override. When set, skips the devcontainer cascade and uses this image directly.
timeout	no	Go duration	Per-job time limit for this agent, e.g. 30m, 1h. When absent, policies.default_timeout applies.
extends	no	string	Name of another agent to inherit fields from. See Inheritance.
env	no	map	Extra environment variables for the agent container. See Environment variables.
keep_container	no	bool	When true, the container is not removed after the job finishes. Effective only in on-prem (direct Docker) deployments; no-op on the hosted service.

* system_prompt is required unless the agent uses extends: to inherit one from a base agent and does not override it.

All agent keys are enumerated above. Unknown keys anywhere in an agent definition are a validation error.

backend

Use claude-code — it is the only functional backend. copilot and aider are accepted by validation but currently run the claude-code adapter regardless of the value set. Always set backend: claude-code.

model

The OpenRouter model ID for the agent, for example:

• anthropic/claude-opus-4-7
• anthropic/claude-sonnet-4-6
• anthropic/claude-haiku-4-5

Model IDs are checked against OpenRouter’s public catalog when events are received (best-effort — validation is skipped on network errors), regardless of provider. The console editor’s save-time validation does not check model IDs. Set the model to match the capability you need — lighter models cost less per job; heavier models handle more complex tasks.

permissions

A non-empty list of authorities the agent is allowed to use. See Permissions for the full authority reference and how the effective set is computed.

permissions: [read, comment, push_branch, open_mr]

Inheritance

extends: names another agent whose fields the current agent inherits. The merge is shallow: each field is taken from the child agent if set, otherwise from the parent. Lists and maps replace whole — nothing is concatenated or merged element-by-element.

agents:
  base:
    backend: claude-code
    model: anthropic/claude-sonnet-4-6
    system_prompt: |
      You are a senior engineer at this company.
    permissions: [read, comment, push_branch, open_mr]

  junior:
    extends: base
    model: anthropic/claude-haiku-4-5   # override model only
    permissions: [read, comment]        # narrower than base — OK

  senior:
    extends: base
    model: anthropic/claude-opus-4-7   # override model only
    # inherits base permissions unchanged

Inheritance cycles (A extends B extends A) are rejected at validation time.

Reserved fields

mcp_servers is accepted by validation for forward compatibility but is not currently functional — the field is never read at dispatch time and no MCP servers are started from this configuration.

Environment variables

The env: block injects additional environment variables into the agent container. Use this to pass LLM provider credentials, tool configuration, or any other runtime values the agent needs.

env:
  ANTHROPIC_BASE_URL: "https://openrouter.ai/api/v1"
  ANTHROPIC_AUTH_TOKEN: "sk-or-v1-..."

Caution

LLM credential keys (OPENROUTER_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY) are treated as secrets. They are stripped from any persisted config snapshots and re-read from the live tenant config at dispatch time. Do not set these keys to static literal values unless you intend them to be used as-is for every job. When your tenant is configured with an openrouter_provisioning_key, Mate mints a per-job sub-key automatically and these env keys are not needed.

Note: the claude-code backend ignores OPENROUTER_API_KEY. To route through OpenRouter, use ANTHROPIC_BASE_URL (set to https://openrouter.ai/api/v1) and ANTHROPIC_AUTH_TOKEN (set to your OpenRouter key).

Container resources

Container CPU and memory are driven by your tenant’s plan tier, not by per-agent configuration. The resources: key that existed in earlier versions has been removed; including it is now a validation error.

Tier	vCPU	Memory
Starter	1	2 GiB
Plus	1	2 GiB
Enterprise	2	4 GiB

Triggers

The triggers: block is an ordered list. Mate evaluates triggers in YAML order; the first matching trigger fires and subsequent entries are not evaluated. One job per event.

See Triggers for the complete trigger reference, including all six event types, if: matcher vocabulary, and evaluation semantics.

triggers:
  - on: label_applied
    label: "agent/review"
    agent: reviewer

  - on: mr_opened
    agent: reviewer
    if:
      target_branch: main
      mr_draft: false

Policies

The policies: block controls rate-limiting and concurrency for the tenant.

policies:
  cooldown: 5m
  concurrency: 3
  default_timeout: 1h

Field	Type	Description
cooldown	Go duration	Minimum time between consecutive jobs on the same repository. Prevents comment-loop spirals.
concurrency	integer	Maximum simultaneous jobs across the tenant. Independent of the plan tier’s mate-capacity ceiling.
default_timeout	Go duration	Used for any agent that does not set its own timeout.

Durations are Go duration strings: 30s, 5m, 1h30m. Unknown keys in policies: are a validation error.

Complete example

version: 1

agents:
  reviewer:
    description: "Reviews MRs for correctness and style"
    backend: claude-code
    model: anthropic/claude-sonnet-4-6
    system_prompt: |
      You are a senior code reviewer. Review the diff carefully.
      Focus on correctness, readability, and obvious security issues.
      Post your findings as a single comment. Be concise.
    permissions: [read, comment]

  fixer:
    extends: reviewer
    description: "Implements issues and opens MRs"
    model: anthropic/claude-opus-4-7
    system_prompt: |
      You are a careful contributor. Implement the issue's requirements
      with the smallest reasonable change, then open an MR for review.
    permissions: [read, comment, push_branch, open_mr]

  ci-assistant:
    backend: claude-code
    model: anthropic/claude-sonnet-4-6
    system_prompt: |
      You are a CI expert. Diagnose the failing pipeline and push a fix.
    permissions: [read, comment, push_mr_branch, touch_ci]
    timeout: 45m

triggers:
  - on: label_applied
    label: "agent/review"
    agent: reviewer

  - on: issue_assigned
    agent: fixer

  - on: pipeline_failed
    agent: ci-assistant

  - on: comment_mention
    agent: reviewer

policies:
  cooldown: 5m
  concurrency: 3
  default_timeout: 1h