Concepts

InstanceCopy Anchor Link

One Kai deployment. Its settings live only in the environment (there is no admin page): who may sign up, who may create workspaces, whether private network addresses or local MCP commands are allowed. See Configuration.

There is no instance administrator. The root user (KAI_ROOT_EMAIL) can always sign up and, if you choose, is the only one who can create workspaces. Everything else is decided per workspace.

WorkspaceCopy Anchor Link

Where a team works. A person can belong to several and switch between them from the menu at the bottom of the sidebar. A workspace has:

• Members with a role: owner (one per workspace), admin or member.
• Keys (BYOK): the provider accounts it pays for, and the models switched on for each.
• MCP servers: the tools it connects.
• Agents: ready-made setups for chats.
• Usage: token counts per day, member and model.

Nothing is shared between workspaces. Every row in the database carries its workspace, and Postgres row-level security keeps workspaces apart.

ConversationCopy Anchor Link

A chat. It belongs to one person and is private to them, even from the workspace's owner. A conversation remembers its model, reasoning effort, agent and the tools turned on for it.

Messages form a tree: editing a message or regenerating a reply adds a branch, and arrows switch between them. When a conversation nears the model's context limit, Kai replaces the older part with a summary (compaction).

Model and keyCopy Anchor Link

A key (Kai calls it a connection) is one provider account: Anthropic or OpenAI, or a gateway that speaks one of their APIs. Each key has a slug, like anthropic, that conversations use to refer to it. A model is one of the key's models switched on for the workspace, like claude-opus-5-5.

Kai knows each model's context window, output limit, reasoning efforts and features from its library service, and falls back to sensible defaults for models it doesn't know.

ToolsCopy Anchor Link

Tools come from MCP servers the workspace adds. A person turns servers (or tool groups) on per conversation, and the model then sees their tools.

Each tool has a permission: ask first (the default), allow, or deny. When Kai asks, the person can allow the call once, for this chat, or always; remembered choices appear under Approvals.

AgentCopy Anchor Link

An agent bundles what a chat starts with: instructions (with variables such as {{user.name}} and {{date}}), and optionally limits on the tools and models the chat may use. Every workspace has a default agent called Kai. Agents can be shared with the workspace or kept private.

RunCopy Anchor Link

When you send a message, Kai starts a run on the server: it calls the model, runs tools, and calls the model again until the reply is done. Runs don't depend on your browser tab. Close it, reload, or open the chat on another device and the reply keeps streaming. A run pauses when it needs you (an approval, a sign-in, a form from a tool) and continues when you answer.