The mental model behind Ai Keeper — the parts that don't show on a screen.
If you have ever been confused about whether a Skill belongs in ClawHub or in Plugins, or whether a remote machine should be Server mode or Client mode, this page is the reference. Every term here corresponds to a real type or service in the codebase.
Server Mode vs Client Mode
Quick answer: Server mode = "this is the workhorse Mac doing the AI stuff." Client mode = "this Mac just talks to the workhorse over the network." Set this in System > Settings > Connection.
Two top-level operating modes. Pick once per machine; both modes can co-exist on a network.
Server mode
The Mac doing the heavy lifting. It runs the models, hosts channels, and lets other devices connect to it. Pick the strongest machine you have.
Runs models, exposes the proxy, hosts channels, accepts remote clients. Best on the host with the most RAM, fastest disk, and your model storage.
- Manages: local runtime instances, OpenAI/Anthropic/Ollama-compatible proxy, automation jobs, channel connectors, RAG index, MCP servers.
- Exposes: management API on the configured port, optional web UI, optional ACP server, optional Node Mesh peering.
- Required for: running any local model, hosting WebChat, scheduling automations, serving API to other tools.
- Required keys: management API key (set before exposing beyond localhost), per-channel webhook secrets, provider API keys in the Secret Store.
Client mode
A "remote control" Mac. It doesn't run any models itself — it just connects to the workhorse Mac and uses its power. Good for a laptop or a less-powerful machine.
Connects to a remote Ai Keeper server for compute. Local UI only; runtime, RAG, and automation defer to the server.
- Manages: local UI state, drafts, personality, memory views — but defers runtime, RAG, and automation to the server.
- Configured with: Remote Server URL + Remote API Key (both copied from the server's Connection panel).
- Cannot: start local instances, host channels, or run scheduled jobs — those live on the server.
- Survives: server downtime — UI stays usable, but model calls fail until the server is reachable.
The Four Registries
Why this matters: Ai Keeper has four different "app stores" for extensions. They sound similar but each does a different thing and each is a different level of risk to install.
Four distinct extension surfaces with different update cadences and trust models.
The official app store. A curated catalog of skills, plugins, and bundles. Browse, click install, done. Use this when you don't want to think about setup.
Marketplace of installable packages. Browse in Download > ClawHub. Per-package trust signals (signature, publisher, install count) visible.
Real add-on programs. Extend the app with new buttons, tools, or features. Think of them like browser extensions — powerful, but only install ones you trust.
App-side plugins that contribute UI, tools, or services through the Ai Keeper plugin protocol. Run in-process. Higher trust than MCP. Manage in Extensions > Plugins.
External tool boxes. Separate programs that give the AI extra abilities (read your email, control your browser, etc.). Industry standard, sandboxed, but still external software.
External processes speaking Model Context Protocol. Browse in Download > MCP (official + Smithery). Configure in Extensions > MCP. Subprocesses with declared scopes. Ai Keeper can also act as an MCP server.
Just instructions. No code, no tools — only words that shape what the AI does. The safest of the four to install.
Reusable instruction/workflow bundles — pure prompt + metadata, no executable code. Manage in Knowledge > Skills or Extensions > Skills.
Trust ordering when reviewing an extension: Skills (lowest blast radius) < MCP (declared scopes, sandboxed subprocess) < Plugins (in-process) < Custom Args / Exec Sessions (full shell). Always grant the smallest surface that does the job.
Identity, Presence, and Routing
Why this exists: when someone messages your AI on Slack today and Telegram tomorrow, the AI needs to know it's the same person. These four services make that work.
Channels, remote clients, and inter-agent traffic flow through four coordination services. Each is independently configurable.
Identity
Connects a Slack user, a Telegram user, an iMessage contact — different accounts of the same person — into one identity, so the AI remembers them across channels.
An Identity Link binds a per-channel account ID to a logical Ai Keeper user. Memory, allowlists, and audit entries attach to the logical user. Configure in System > Advanced > Connectivity or implicitly via DM Pairing handshakes.
Presence
Decides which agent answers an incoming message and keeps the conversation thread together across messages.
The Presence Service maintains a routing session per (channel-type, channel-id). Picks the handling agent or workspace and persists context across messages. Look here first when a channel "loses memory" mid-conversation — the session ID may have rotated.
DM Pairing
A guest list per channel. Strangers can't DM the AI unless they're on the list (or the channel is open to everyone).
Per-channel sender allowlist that gates Auto-Reply. Records welcome/rejection templates and tracks paired senders. Always enable on public channels (Telegram bots, Discord, Slack) before turning Auto-Reply on.
Channel Health
A status light per connector. Green = working, amber = quiet, red = broken.
The Channel Health Monitor records last-activity, errors, and disabled state per connector. Shared Inbox decorates with green/amber/red. Tracks inbound activity — outbound delivery failures must be checked on the upstream API.
Protocols In Use
What this means: a protocol is just an agreed-upon way of talking. Different apps "speak" different languages, and Ai Keeper supports the most common ones so almost anything can connect to it.
The most common one. Most coding tools and AI libraries already know how to speak this. If an app says "OpenAI API key", point it at Ai Keeper's URL and it works.
Default REST surface for the proxy and most local engines. Used by VS Code/Cursor extensions, LangChain, LlamaIndex, and anything else expecting OpenAI's API shape.
The format Claude apps speak. If you use Claude Code or other Anthropic-flavored tools, point them here.
Alternate API surface; default for Claude Code and the Anthropic SDK. Exposed on the proxy. omlx serves Anthropic format natively for local Claude-style clients.
For tools that only know Ollama. Drop-in replacement so they keep working without code changes.
Drop-in routes for clients hardcoded to Ollama's API shape. Exact endpoint paths shown in System > API Access.
How AI agents borrow tools from each other. External programs (an email reader, a calendar, a scraper) can offer their abilities to Ai Keeper this way.
Tool/resource exchange protocol. Ai Keeper is both an MCP client (consuming tools) and an MCP server (exposing its tools to other agents).
How AI agents talk to each other. Different from MCP — instead of one agent borrowing a tool, two agents have a structured back-and-forth conversation.
Structured agent-to-agent messaging, distinct from MCP's tool-call shape. Use for hand-offs (across machines if Node Mesh is configured), preserving message structure.
Connects multiple Ai Keeper machines into a small network so they can share work.
Peer-discovery and routing layer beneath ACP. Unsigned peers are rejected by default; pairing must be explicit.
Full Glossary
How to read this: the first line of each entry is plain English. The second line is the precise technical meaning for when you're configuring something.
Server vs Client — is this Mac the workhorse or the remote control? See top of page.
Top-level operating mode. Distinct from Work Modes (saved profiles).
The "motor" that runs a model. Different motors, different strengths.
Backend process family: omlx, vllm-mlx, vmlx, mlx-lm, llama.cpp.
One running copy of a model with all its settings. Like a saved configuration that can be started or stopped.
Runnable configuration: engine + port + context window + output limit + sampling + tool policy + access policy + custom args.
What kind of job an instance does — chat, look at images, search files, audio. The app uses this to send the right work to the right model.
Specialization tag (LLM, VLM, Embedding, Reranker, Audio STT/TTS/STS) that constrains routing — e.g. Documents only call Embedding-role instances.
A single web address that other apps point to. Behind it, Ai Keeper picks which model to actually use.
Unified API layer. Routes OpenAI/Anthropic/Ollama-style requests to local instances or cloud providers via failover chains.
The remote-control channel — used by the web dashboard and other Macs to drive this one. Always password-protected.
Authenticated control plane behind the Management API Key. Used by web UI, remote clients, status endpoints, and orchestration.
A word-piece. AI models read and write in tokens, not whole words. Roughly: 1 token ≈ 0.75 words in English. Bills are usually per token.
Smallest unit consumed and produced by the model. Used to measure context window usage, output cost, and rate limits.
How much the AI can "see" at once — your prompt, history, attachments, and reply, all combined. Bigger window = better memory but more RAM.
Total token budget available per request. Consumed by system prompt, history, tool schemas, retrieved documents, and response.
When a chat gets too long, the app summarizes the older parts so it can keep going.
Conversation summarization triggered at the auto-compact threshold. Configured in System > Settings.
"Retrieval-Augmented Generation" — fancy name for: the AI searches your files for relevant bits, then answers using them.
Retrieval-Augmented Generation. Local files are indexed; embeddings come from the configured Embedding instance; top-K chunks are inserted into the prompt at answer time.
A standard for letting AI agents borrow tools from external programs.
Model Context Protocol — tool/resource exchange. See Protocols section.
A standard for AI agents to talk to each other in structured back-and-forth.
Agent Communication Protocol — agent-to-agent messaging. See Protocols section.
A bundle of instructions that tells the AI how to do a task. No code, just prompts. Safest extension type.
Reusable instruction/workflow bundle. One of the four registries. Lowest-trust — prompt + metadata only, no executable code.
A real add-on program that extends the app with new buttons, tools, or features.
App-side extension contributing UI, tools, or services. One of the four registries. In-process — higher trust than MCP.
The official "app store" inside Ai Keeper — browse and install vetted skills/plugins/bundles.
Curated marketplace of installable packages. Per-package trust signals visible.
An auto-action that fires when something happens. "Whenever a Slack message arrives, log it" is a hook.
Event-triggered action: pre-prompt, post-tool, on-channel-message, on-error. Can inject context, run a skill, log memory, call a webhook, or exec.
A permanent rule for the AI. "Never share my address." It applies forever, in every chat.
Persistent instruction applied globally or per agent. Survives session resets.
A recurring AI task that wakes itself up on a schedule (every minute, every hour, etc.). Always cap how many times it runs.
Recurring agent turn for monitoring or background follow-up. Always set max-iterations to prevent runaway token spend.
A saved "preset" for a kind of task. Pick one and the app sets up the right model, memory, and tools for that activity.
Saved profile bundling model choice, execution mode, memory behavior, autonomy, web tools, starter assets, and package requirements.
A backup plan: try provider A first; if it fails, automatically try B, then C.
Ordered provider/instance fallback. Trips on rate-limit, auth failure, latency, or downtime. Per-entry cooldown and key rotation.
A way to keep different kinds of traffic separate so important requests don't get stuck behind big batch jobs.
Server-side routing lane that groups endpoints by purpose, priority, or tenant. Use to isolate batch from interactive traffic.
Connects "this Slack user" and "this Telegram user" as the same person, so the AI doesn't treat them as strangers.
Per-channel account ID ↔ logical Ai Keeper user binding. Memory, allowlists, and audit entries attach to the logical user.
The traffic cop that decides which AI agent answers an incoming message and keeps the conversation tied together.
Routing-session manager. Picks the agent for inbound messages and preserves context across the session.
A named bundle of tools you can hand to an agent in one go, like a "web tools" pack.
Named bundle of individual tools assigned to agent roles. Easier to audit and rename-safe than per-tool toggles.
A persistent terminal window the AI can keep using, instead of starting a new one for every command.
Persistent shell/REPL handle the model attaches to. Avoids spawn-per-call overhead. Cap lifetime to limit stale state.
A diary of every tool the AI used and every action it took. Read it when you want to know what happened.
Append-only event log: tool calls, approvals, exec sessions, channel events, identity changes.
When idle, the AI writes journal entries and ideas in the background. Suggestions, not gospel.
Idle-synthesis pipeline producing diary entries, memory-palace pages, and insights. Suggestion-grade, not authoritative memory.
A document describing the AI's permanent voice and tone. Different from instructions you give in a single chat.
Long-form persona document. Distinct from per-conversation system prompts and per-agent role prompts.
A live preview area in Lab where you can see the AI's HTML, charts, or interactive output rendered for real.
Live HTML/chart/interactive output surface in Lab for previewing rich tool outputs without leaving the app.