Key Concepts
Five things fit together in Mesa: tenants hold everything, bots are what people talk to, agents decide how a bot answers, channels are where it answers, and API keys let it call a model at all.
Tenants
A tenant is the top-level unit. Everything — bots, channels, API keys, configuration — belongs to exactly one.
- Personal tenants map 1:1 to a user account
- Organization tenants are shared workspaces where all members benefit from what admins set up
- When an admin connects something to an org tenant — a bot, a key, a tool integration such as GitHub — the members get the benefit of it
All functionality is tenant-scoped, not user-scoped. This is a fundamental architectural principle: your access to a thing follows from your membership of its tenant.
Bots
A bot is a configured assistant within a tenant: a name, a model provider and model, sampling temperature, context and history settings, and the channels it is connected to. A tenant can have several bots — a customer-facing one and an internal one can differ in model, channels and authorized chats without interfering. See Creating a bot.
Agents
An agent is one configured way of answering: a model, a set of instructions, and the tools it may use. There is no fixed catalogue of agents that ships with Mesa — an agent is a row in your deployment's database, versioned and edited through the admin console, and the set you have is whatever your deployment has defined.
Each bot has a route specification that decides which agent takes each message — by keyword rules, by asking a model, or rules-first with a model fallback. See AI agents.
Channels
A channel connects a bot to a communication platform. Two are supported:
| Channel | Description |
|---|---|
| Telegram | Bot API integration with webhook support |
| Inbound/outbound email processing |
A bot answers only in chats an admin has explicitly authorized — connecting a channel is not enough by itself. See the Telegram and Email guides.
API Keys
API keys let bots call a model provider — OpenAI or Anthropic (plus, on deployments that enable it, a private-LLM provider for a separate purpose). Mesa supports:
- Global keys — provided by the deployment, shared by whatever falls under their scope
- BYOK (Bring Your Own Key) — your own provider account, and your own bill
When a bot needs a key, Mesa walks the scopes from most specific to least, preferring BYOK over global within each scope: bot BYOK → bot global → tenant BYOK → tenant global. The first match is used. See API keys.