MATE — The Command Center for AI Agents

Change the prompt, the model or who may use an agent from a dashboard — no code change, no redeploy. Self-hosted, on Google ADK or LangGraph, with any of 50+ LLM providers.

Live demo · Quick Start · Docs · Changelog

Run it in one command:

docker run -d -p 8000:8000 -e AUTH_PASSWORD=change-me -e GOOGLE_API_KEY=your-key ghcr.io/antiv/mate:latest
# open http://localhost:8000 and log in as admin / change-me

(Add -v mate-data:/app/data -e DB_PATH=data/my_agent_data.db to keep your agents across restarts — see Quick Start.)

Used in production

• Goal Navigator runs on MATE in production — case study.
• MVP-Soft, LLC, a US software consultancy, builds with MATE — MATE at MVP-Soft.

What you get

• 🎨 Build without code — draw agent hierarchies, attach tools and MCP servers, and edit prompts on a canvas. Every change is live, versioned and one click from a rollback.
• 🏛️ Govern production — RBAC per agent, cost in US dollars per agent and project, budgets that warn or block, guardrails, alerts to Slack, Discord, email or a webhook, and audit logs.
• 🧪 Ship without regressions — eval suites scored by exact match, similarity or an LLM judge, a regression webhook, and a Playground that compares models and prompts side by side.
• 🔌 Plug in anywhere — an embeddable chat widget, an OpenAI-compatible API, A2A, and every agent served as an MCP server.

Created by Ivan Antonijević. If MATE saves you a redeploy, give it a ⭐ — it is how other people find it.

---

Try it without installing anything

These run on a live MATE instance. No signup, no install.

• Play the murder mystery demo — a multi-agent game running on MATE. No signup: you question suspects, and a wrong accusation costs you
• Build an agent in the browser — the embeddable wizard provisions a working agent and lets you chat with it (interface in Serbian)

The dashboard behind them needs an account — everything below sets up your own instance, which behaves the same way.

---

The Problem with Agents in Production

You built an agent. Now you need to tune the prompt. Swap the model. Restrict access for specific users. Figure out what it's actually costing you. And make sure yesterday's behavior still works after today's changes.

Without a control layer, every one of those is a code change, a commit, and a redeploy. MATE is that control layer — it adds what production needs without touching your agent code.

A single agent in a notebook is easy. A hierarchy of agents serving real users is not.

• Iteration is slow. Tweaking a prompt means editing code, committing, and redeploying. By the time you've tested three variations you've wasted half a day.
• Governance is messy. Who can call the admin agent? The finance agent? You need per-agent access control, but ADK doesn't ship with RBAC.
• Costs are invisible. You know tokens are being spent, but you can't see which agent is the expensive one, or whether it's prompt tokens, response tokens, or reasoning tokens eating your budget.
• Regressions are silent. You improve one prompt and unknowingly break another agent's logic. You only find out when a user complains.

---

Three Things MATE Gives You

🎨 The Studio — Build and iterate without touching code

A drag-and-drop canvas where you create agents, draw parent→child connections, and attach tools without writing JSON or Python. Change a prompt, swap a model (from Gemini to GPT-4o to local servers like Ollama, LM Studio, llama.cpp, LocalAI, or Llamafile), or restructure an entire hierarchy — and it takes effect immediately, no redeploy.

Every agent lives in the database. Every change is versioned. Roll back to any previous configuration in one click.

When a conversation goes somewhere you didn't expect, Trace Replay plays it back on the same canvas: agents light up in the order they ran, the hand-off to a sub-agent shows on the edge between them, and each agent shows the model or tool it is using, how long it took, and whether its fallback model had to answer.

🏛️ The Control Room — Govern what runs in production

RBAC per agent means the finance team's agent is never visible to basic users, without any custom middleware. Every model call is priced in US dollars as it is logged — from OpenRouter's and LiteLLM's price lists, or a price you set — so the Usage page shows what each agent and project actually costs, next to the four token buckets (prompt, response, thoughts, tool use).

Set budgets in tokens or dollars per user, agent or project that warn or block, and alert rules that post to a webhook, email, Slack or Discord when agents fail, a guardrail keeps firing, a fallback model takes over, or a budget runs low. Add guardrails (hallucination scoring, PII, prompt injection) from the dashboard. Audit logs capture every configuration change for compliance.

🧪 The Lab — Know before you ship

The Eval Framework runs your agents against a test suite automatically. Write expected outputs; MATE invokes the live agent, scores the response (exact match, semantic similarity, or LLM-as-Judge), and tracks pass rates across versions as a chart.

Set a regression threshold and MATE fires a webhook if a new version scores more than 5 points below the previous one. Catch prompt regressions before users do.

The Playground answers "which model, which prompt?" before you change anything: run one prompt, or an agent's whole eval suite, on two or three variants of the agent — another model, other instructions, an older version — and compare score, reply time and cost in dollars side by side.

---

Quick Start

git clone https://github.com/antiv/mate.git && cd mate
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.lock

cp .env.example .env
# Set GOOGLE_API_KEY (or any supported provider key), AUTH_USERNAME and AUTH_PASSWORD

python auth_server.py
# Dashboard: http://localhost:8000  — log in with AUTH_USERNAME / AUTH_PASSWORD
# (left empty, they are admin / mate; MATE_ENV=production refuses that default)

Or with Docker, from the published image (no clone needed):

docker run -d --name mate -p 8000:8000 \
  -e AUTH_PASSWORD=change-me -e GOOGLE_API_KEY=your-key \
  -e DB_PATH=data/my_agent_data.db -v mate-data:/app/data \
  ghcr.io/antiv/mate:latest

Or build it yourself with docker-compose up (it needs AUTH_PASSWORD set in .env).

Dependencies

requirements.txt lists the direct dependencies; requirements.lock pins every package, with hashes, and is what Docker, CI and the Quick Start install. After editing requirements.txt, or to pick up new releases, regenerate the lock with uv and run the tests before committing both files:

uv pip compile requirements.txt -o requirements.lock --universal --python-version 3.11 --generate-hashes
# add --upgrade to move everything to the latest allowed versions,
# or --upgrade-package litellm to move just one
python -m unittest discover -s shared/test -p "test_*.py"

On the 1st of every month, .github/workflows/dependency-upgrade.yml does this with --upgrade, taking only releases at least a week old, runs the tests on the result in a job without write access, and opens a pull request when anything moved (it can also be started by hand from the Actions tab). The exact pins in requirements.txt, google-adk and SQLAlchemy below 2.1, are moved by hand after reading their changelogs. The workflow needs Settings → Actions → General → Allow GitHub Actions to create and approve pull requests; with the default token the pull request gets no CI run of its own, so set a DEPENDENCY_PR_TOKEN secret if you want one. Dependabot keeps the workflows' own actions current.

Migrations run automatically on startup. Default database is SQLite.

---

Screenshots

Dashboard Overview

Monitor usage, active agents, system health, and request trends at a glance.

Agent Management

View and manage your full agent hierarchy — models, parent relationships, and status per project.

Agent Visual Builder

Drag-and-drop canvas for building agent hierarchies. See tool and MCP nodes attached to each agent, click to configure them inline, and create connections without touching JSON.

Trace Replay

Play a traced conversation back on the Visual Builder canvas: which agent ran when, the hand-off from the root agent to a sub-agent, the tools it called, and a fallback model answering when the primary failed. The whole session plays as one run, turn after turn. (MP4 · guide)

Work Room

A built-in chat interface inside the dashboard. Pick any root agent from the card grid and start a conversation — no embed code, no browser tab switching. Sessions are auto-titled and persist across page reloads. The default landing page after login.

When the agent responds with code, the canvas panel opens automatically to the right of the chat. Code never clutters the conversation — it goes straight into a full-featured editor. HTML, JavaScript, CSS, SVG and Python run with one click in a sandboxed frame, apart from the dashboard — Python via Pyodide (WebAssembly), in the browser. Dart and Flutter applications are executed directly in the browser via a seamless, zero-install DartPad integration that bypasses the code view to show the interactive application immediately. The panel is resizable by dragging the divider. Any edits made in the canvas are automatically included in the next prompt, so you can ask the agent to modify its own output without copy-pasting.

With the Canvas Panel, you can view and edit the generated code in a full-featured Ace Editor, and run/execute it in a sandboxed environment with a single click:

Editing generated code in the Canvas Panel

Previewing and running the generated code in a sandboxed iframe

Agent Configuration

Edit every aspect of an agent: model, instruction, RBAC roles, memory blocks, tools, MCP servers, planner, and schemas.

Tool Configuration

Toggle built-in tools or provide custom JSON — Google Drive, Search, Image, Memory Blocks, Code Executor, File Search, and more.

Chat Interface

Multi-agent chat with event tracing, tool calls, and persistent memory.

Usage Analytics

Token usage trends, agent performance, activity-by-hour, and per-agent success rates.

Token Usage Details

Drill into individual request logs — prompt / response / thought / tool-use token breakdown per request.

---

Why MATE vs. raw ADK

Challenge	Raw ADK	MATE
Change a prompt or model	Edit code, redeploy	Dashboard edit, instant
Switch LLM providers	Code change per agent	Change model_name in config (ollama_chat/llama3.2, lm_studio/qwen2.5, openai/gpt-4o, …)
Access control per agent	Build your own	Built-in RBAC, no code
Cost visibility	DIY	Cost in US dollars per agent, project and user, plus a 4-type token breakdown
Spending limits	DIY	Token and dollar budgets that warn or block, with alerts
Regression testing	Manual	Automated eval suite with LLM-as-Judge
Compare models and prompts	Ad-hoc scripts	Playground: variants side by side with score, latency and cost
Multi-team isolation	Manual	Project-scoped agent hierarchies
Embed chat on a website	Not included	Single <script> tag
Agents that modify agents	Not included	create_agent tool, RBAC-protected

---

Features

Work Room

• Built-in chat interface in the dashboard — pick a root agent from the card grid and start talking, no embed code required
• Sessions are automatically titled (LLM-generated) and persist across page reloads
• Supports the same streaming SSE, tool-use indicators, and markdown rendering as the embeddable widget
• The default landing page after login — useful for internal teams who live in the dashboard
• Canvas panel: code blocks auto-open in a side panel with Ace Editor instead of rendering in chat
• Execute HTML, JavaScript, CSS, SVG and Python (Pyodide, WebAssembly) in a sandbox, apart from the dashboard; execute Dart and Flutter apps in-browser using a zero-setup DartPad integration that bypasses code view to show the live app directly
• Canvas edits are automatically attached to the next prompt — iterate on code without copy-pasting
• Drag the chat/canvas divider to resize; canvas closes and resets when a new session starts

The Studio

• Database-driven agent management — every field editable from the dashboard, zero redeploy
• Drag-and-drop Visual Builder (React Flow) — create agents, draw parent→child edges, configure tools and MCP nodes inline
• 50+ LLM providers via LiteLLM: Gemini, GPT-4o, Claude, Llama (Ollama, LM Studio, llama.cpp, LocalAI, Llamafile), DeepSeek, OpenRouter, and more
• Agent version history with one-click rollback
• Self-building agents — the create_agent tool lets agents create, update, and delete other agents at runtime (admin-only, RBAC-protected)
• Import/export agent configurations as JSON

The Control Room

• RBAC per agent: assign roles in the dashboard, no middleware to write
• Google (OIDC) and GitHub OAuth 2.0 SSO with automatic user provisioning; Basic Auth always available
• Cost in US dollars for every model call, from OpenRouter's and LiteLLM's price lists or prices you set; calls without a known price are shown as such, never as $0
• Token tracking across four types: prompt, response, thoughts, tool-use — per agent, per session, per user
• Rate limits and budgets per user/agent/project: requests, tokens, and US dollars per day or month, with warn or block
• Alert rules for agent errors, guardrail bursts, fallback-model use and budget thresholds, sent to a webhook, email, Slack or Discord
• Hallucination guardrail: LLM-scored factual consistency check per response, configurable threshold
• Function call and model-level guardrails
• Append-only audit log of every configuration change, with configurable retention — evidence toward EU AI Act Art. 12 record-keeping
• Art. 50 AI disclosure shown by default wherever an agent is public, and not removable without a recorded reason
• Content-Security-Policy on every page, with per-request nonces; agent-written code in the Work Room runs on a sandboxed page
• Prometheus metrics at /metrics
• OpenTelemetry distributed tracing

The Lab

• Eval Framework: test suites per agent with exact match, semantic similarity, or LLM-as-Judge scoring
• Auto-invocation — evals call the live agent; no copy-pasting responses
• Score history chart across versions (Chart.js)
• Regression webhooks: fires when a new version drops more than 5 points vs. the previous
• Playground: one prompt or the eval suite on 2–3 variants (model, instructions, stored version), with score, reply time and cost side by side

Embeddable Widget

• Single <script> tag deploys a floating chat button on any website
• Per-key RBAC, origin restrictions, and scoped user namespacing
• Widget admin panel (/widget/admin?key=...) for non-technical teams: edit greeting, theme, colors, memory blocks, and files without dashboard access
• Light/dark/auto theme, configurable accent color, optional file attachments
• Page context injection: widget auto-reads the embedding page's URL and title and passes it to the agent as conversation context

OpenAI Compatibility & External Clients

• OpenAI-compatible API bridge mapping MATE agents as standard LLM models at /v1
• Point an agent at an OpenAI-compatible endpoint you already run, and MATE's RBAC, guardrails, evals and cost tracking apply to it
• Expose any root agent as a model with a single switch in the dashboard
• Secure access using Personal Access Tokens (PATs) hashed with SHA-256 in the database
• Integration with external coding engines, CLI tools, and IDE extensions (OpenCode, Continue, Cline/Roo Code)

Infrastructure

• SQLite (dev), PostgreSQL, MySQL 8 — auto-migrations on startup, drivers included
• Docker Compose with health checks
• Artifact storage: local, S3, or Supabase
• MCP: agents exposed as MCP servers (Claude Desktop, Cursor) + MCP tool consumption
• A2A: every agent served at /a2a/{agent} with its agent card (A2A protocol 1.0, and 0.3 methods)

---

Setup

Environment Variables

# Minimum required
GOOGLE_API_KEY=your_key_here          # or any supported provider

# Database (SQLite by default)
# DB_TYPE=sqlite (default), postgresql, mysql
# DB_HOST=localhost  DB_PORT=5432  DB_NAME=mate_agent  DB_USER=...  DB_PASSWORD=...

# Authentication
AUTH_USERNAME=admin
AUTH_PASSWORD=change-me
MATE_ENV=production                   # refuses insecure defaults at startup

# SSO (optional)
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
SECRET_KEY=<random-32-byte-hex>       # required for SSO sessions

# Additional LLM providers (only set keys for providers you use)
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
OPENROUTER_API_KEY=...
OLLAMA_API_BASE=http://localhost:11434
# Local API servers (optional base URL overrides)
LM_STUDIO_BASE_URL=http://localhost:1234/v1
LLAMACPP_BASE_URL=http://localhost:8080/v1
LOCALAI_BASE_URL=http://localhost:8080/v1
LLAMAFILE_BASE_URL=http://localhost:8080/v1

# Optional features
MCP_EXPOSED_AGENTS=agent1,agent2      # expose agents as MCP servers
RATE_LIMIT_ENABLED=true               # enforce rate limits and budgets
ALERTS_ENABLED=true                   # evaluate alert rules
CSP_MODE=enforce                      # report-only (default), enforce or off
OTEL_TRACING_ENABLED=true
AUDIT_RETENTION_DAYS=365

Database Migrations

python shared/migrate.py status     # check pending migrations
python shared/migrate.py run        # apply manually (auto-runs on startup)
python shared/migrate.py create     # scaffold a new migration in every dialect

Docker

docker-compose up --build           # full stack with dashboard
docker-compose up -d --build        # background

---

Testing

# All tests
python -m unittest discover -s shared/test -p "test_*.py" -v

# With coverage
coverage run -m unittest discover -s shared/test -p "test_*.py"
coverage report --include="shared/utils/*,server/*,auth_server.py"

1,400+ tests covering agent management, RBAC, migrations, guardrails, CSP, costs and budgets, A2A, tracing, and more.

---

Embeddable Chat Widget — One Backend, Many Sites

A single MATE instance can power AI chat across multiple websites simultaneously. Each site gets its own widget key scoped to a specific agent, with independent appearance, memory, and access rules.

<!-- Drop this before </body> on any website -->
<script
  src="https://your-mate-instance.com/widget/mate-widget.js"
  data-key="wk_abc123..."
  data-server="https://your-mate-instance.com"
></script>

A floating chat button appears instantly. No build step, no framework dependency.

Multi-site example

MATE instance
├── key: wk_aaa  →  support_agent    →  company-support.com   (English, light theme)
├── key: wk_bbb  →  sales_agent      →  company-sales.com     (dark theme, no attachments)
└── key: wk_ccc  →  docs_agent       →  docs.company.com      (RAG over product docs)

Each key is independent: different agent, different greeting, different allowed origins, different color scheme.

Page context awareness

When a user opens the widget on a product page, the widget automatically reads the page URL, title, and meta description and passes them to the agent as conversation context. The agent knows which page the user is viewing without any custom integration — just enable "Inject page context" in the widget admin panel.

Widget admin panel

Each key has a standalone admin panel at /widget/admin?key=.... Non-technical teams can manage appearance, greeting, memory blocks, and uploaded files without touching the main dashboard.

Setting	Admin panel
Widget title and greeting	✓
Light / dark / auto theme	✓
Button and accent color	✓
Show / hide file attachments	✓
Page context injection toggle	✓
Agent instruction and model	✓
Memory blocks (company info, FAQs…)	✓
RAG file upload	✓

Full documentation: docs/user/widget.md

---

MCP Integration

MATE exposes agents and tools as MCP servers, compatible with Claude Desktop, Cursor, and any MCP client.

# Expose specific agents as MCP servers
export MCP_EXPOSED_AGENTS=creative_agent,support_agent

Each exposed agent gets endpoints at /agents/{name}/mcp/*, and GET /mcp lists the ones you may use with their URLs. Built-in MCP servers: Image Generation (/images/mcp) and Google Drive (/gdrive/mcp).

Clients authenticate with a personal access token from the dashboard's account menu, sent as Authorization: Bearer mate_pat_.... The token's user needs a role in ALLOWED_API_ROLES (default admin, developer) and, for an agent, a role the agent allows.

Full documentation: docs/dev/mcp-servers.md

---

Dashboard Routes

Route	Purpose
/dashboard/workroom	Work Room — chat with any agent directly in the dashboard (default after login)
/dashboard	Overview — usage stats, system health
/dashboard/agents	Agent hierarchy, configuration, Visual Builder
/dashboard/users	User management and role assignment
/dashboard/usage	Cost in US dollars and token analytics, per agent, project and user
/dashboard/rate-limits	Rate limits and budgets (requests, tokens, US dollars)
/dashboard/alerts	Alert rules and where they are sent
/dashboard/settings	Model prices, default image model
/dashboard/evals	Test suites, score history, regression tracking, Playground
/dashboard/audit-logs	Audit trail viewer
/dashboard/migrations	Database migration management
/dashboard/docs	Documentation: user and developer guides, generated reference, search, and the API explorer (Swagger + ReDoc)

---

Additional Documentation

• docs/ — all user and developer guides plus the generated reference; the same pages are searchable in the dashboard under Documentation
• docs/user/eu-ai-act.md — EU AI Act: what applies when, and what MATE does and does not do about it
• docs/user/external-agents.md — governing an agent that runs outside MATE
• docs/dev/openai-compatibility.md — OpenAI-compatible API bridge, PAT generation, and external client setup (OpenCode, Continue, Cline)
• docs/user/widget.md — embed code, widget admin panel, JS API, security, theming, page context
• docs/dev/sso-setup.md — Google and GitHub SSO setup, enterprise domain restrictions, session security
• docs/dev/evals.md — eval methods, regression alerts, LLM-as-Judge configuration, API reference
• docs/dev/mcp-servers.md — MCP server configuration, client setup (Claude Desktop, Cursor), protocol details
• docs/user/rate-limits.md — per-user/agent/project rate limits and budgets in tokens and US dollars
• docs/user/usage-and-audit.md — cost in US dollars, token analytics, audit log

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, code style, and PR guidelines.

Security

For security best practices and vulnerability reporting, see SECURITY.md.

License

Apache License 2.0 — see LICENSE.