Glossary

This page defines terms used throughout the Fermix documentation. Entries are grouped loosely by theme and link to the relevant reference pages where appropriate.

Runtime and platform

Term	Definition
BEAM	The Erlang virtual machine that executes Elixir code. Fermix runs as a single BEAM instance; all subsystems (agent, channels, web, memory) share one process space with no HTTP bridges between them.
OTP	Open Telecom Platform. The Erlang/Elixir library of supervisor trees, GenServers, and fault-isolation primitives. Fermix leans on OTP for process supervision, crash recovery, and scheduled work. See supervision.
Umbrella	An Elixir project structure that groups multiple applications under one build root. Fermix is organized as an umbrella with five runtime apps: fermix_core, fermix_channels, fermix_web, fermix_nif, and fermix_opik.
FERMIX_HOME	The root directory for all Fermix state: config.toml, bootstrap files, skills, traces, logs, and the memory database. Defaults to ~/.fermix; override with the FERMIX_HOME environment variable.

Agent and loop

Term	Definition
MainAgent	The persistent top-level agent process (FermixCore.Agents.MainAgent). It holds runtime-context cache state, composes the prompt, reads conversation history, fetches tools, and delegates each turn to AgentLoop. There is exactly one MainAgent per running daemon.
AgentLoop	The bounded LLM/tool iteration (FermixCore.AgentLoop). It calls the configured provider, parses tool calls, executes them through the capability registry, appends results, and continues until the provider returns a final response or the iteration cap is reached (default 100 for interactive turns; a system-side setting, not a config.toml key). See the agent loop.
Conversation key	The three-tuple {channel, chat_id, thread_scope} that uniquely identifies one logical conversation. Used for per-conversation history, single-flight scheduling, and compaction state.
Single-flight	The guarantee that at most one agent turn runs per conversation key at a time. Newer same-conversation messages are appended to a FIFO pending queue and run in arrival order after the active turn completes; a new message does not cancel the in-flight turn. (Only /stop cancels a running turn.)
Ultra mode	A run-mode of the normal turn triggered by the /ultra channel command. It tags the turn run_profile: :ultra, which unlocks wider subagent caps (up to ~50 narrow probes, up to 12 concurrent) and activates an exhaustive-mode prompt addendum. It is not a separate orchestrator; workers nest under the parent trace like regular subagents.

Capabilities and tools

Term	Definition
Capability	A single registered entry in CapabilityRegistry. Every capability has a name, description, JSON Schema parameters, a kind, a policy_class, and an executor. “Capability” and “tool” are used interchangeably in agent-facing language. See capabilities and tools.
Capability kind	The origin of a capability. :builtin means a pure Elixir tool shipped with Fermix; :skill means a SKILL.md-defined sub-agent; :mcp means a tool discovered from an outbound MCP server.
Tool	Synonym for a built-in capability from the model’s perspective. Skills and MCP tools also appear as tools in the provider’s tool list.
Plugin	An integration that owns a surface (an API or a vault) and registers its own tools. The Gmail, Google Calendar, and Google Drive plugins are bundled and always present; additional plugins install from a signed catalog bundled in the binary, verified with sha256 + cosign before activation.
Plugin rail	How an installable plugin runs, and therefore where its tools execute: HTTP (declarative request templates executed in-VM, https-only behind an SSRF floor) and local MCP (a supervised local process whose discovered tools register as <plugin>_<tool>) both run on this machine; a hosted MCP plugin ships no code at all and runs on the vendor’s servers. The setup page states which rail a plugin uses before you install it.
Hosted MCP plugin	An installable plugin whose tools execute on the vendor’s own servers rather than on this machine. Its artifact holds no code: a signed manifest fixing the endpoint it connects to, the exact set of tool names the agent can be offered, and every tool’s input and output schema. Fermix re-checks the live service against that signature on each connect — a tool the vendor added is ignored, and a signed tool that has gone missing or whose schema changed fails the whole set, so none of that plugin’s tools register rather than the agent’s reach widening quietly. See plugins.
Skill	A filesystem-backed sub-agent defined by a SKILL.md file. Skills live under priv/skills, ~/.fermix/skills, or plugin roots. Each skill carries its own instructions and tool boundary. Trust is derived from location: bundled and local skills run with operator trust; plugin-loaded skills run with guest trust. See skills.
Skill curation	The background pass that reads the owner’s own recent messages, finds tasks they repeat that no existing skill or tool covers, and proposes a skill for them. It only proposes: nothing is written without an explicit approval, it audits only the skills it created itself, and an archive moves the skill aside reversibly instead of deleting it. Driven by /skills and switched off with enabled = false under [fermix_core.skill_curation]. See skills.
MCP	Model Context Protocol. Fermix can act as both an MCP server (exposing its tools to external clients) and an MCP client (consuming tools from outbound MCP servers). Discovered MCP tools are registered as :mcp capabilities. See MCP.
Policy class	The trust-based classification of a capability: :read_only, :read_write, :exec, :network, :external_api, or :gui_control. The last covers desktop computer use and is operator-only (never delegated to sub-agents). The capability filter uses policy class to restrict what a caller may invoke — a guest-trust caller is limited to :read_only classes, and additionally never receives a capability marked owner-only (one whose result is the owner’s own data).
Computer use	An experimental capability, off by default, that lets the agent control the host desktop directly — taking a screenshot to see, then driving the mouse and keyboard one action per call. It carries the :gui_control policy class, is operator-only, and is never delegated to sub-agents. Enabling it installs a separate native helper (a checksum-verified download) from the setup page and flips a feature flag; what it is allowed to do is derived from the sandbox mode. See capabilities and tools.
Hidden capability	A capability registered with hidden_from_agent?: true. It is excluded from the tool list sent to the model but remains callable from internal code paths.
Owner-only capability	A capability whose return value is the owner’s own data — workspace file reads, scheduled-job reads, memory sources. Marked with an owner_only? flag beside its policy class; the registry filters these out of a guest’s surface entirely, so for a guest the tool is absent from the prompt, the provider wire, and dispatch by name.
Deferred tool	A plugin or MCP tool whose full JSON Schema is kept off the provider wire by default (tool-schema deferral, on by default). The model discovers and invokes deferred tools on demand through tool_search (search the catalog), tool_describe (fetch one tool’s schema), and tool_call (invoke by name). Built-in tools stay inline.

Channels and ingress

Term	Definition
Channel	A surface through which a message reaches the agent: Telegram, WhatsApp, Slack, Discord, Signal, an ACP client, or the local CLI. All channels normalize inbound messages and dispatch through MainAgent. See channels.
ACP (Agent Client Protocol)	The protocol an external client speaks to drive Fermix — the Zed editor, or a Buzz coding harness. The client launches fermix acp, which bridges the client’s standard input and output to the running daemon over a Unix socket (a local channel between processes on the same machine); each session becomes an ordinary Fermix conversation with the real prompt, tools, sandbox, memory, and telemetry rather than a second agent. On by default. Slash commands do not exist on that surface. See ACP clients.
ACP client identity	A posting identity an ACP client presents when it connects. Fermix remembers it across sessions under FERMIX_HOME, so a coding run delegated through that client can be delivered back to it when it finishes. fermix acp forget is the only way to remove one; turning the ACP surface off stops new connections and deletes nothing. See ACP clients.
Ingress	The trust-resolution and authorization layer (FermixChannels.Gateway.Authorizer) that runs before a message reaches the agent. It maps an inbound sender to operator or guest trust, or denies the request. See ingress and trust.
Gateway	The shared entry point (FermixChannels.Gateway.ingest/2) that normalizes messages, runs ingress authorization, dispatches slash commands, and hands turns to the per-conversation queue (processed in arrival order, first in first out).
Transcription backend	The speech-to-text engine that converts inbound voice notes and audio attachments to text before the turn reaches the agent, selected by backend under [fermix_core.transcription]: openai (default, gpt-4o-mini-transcribe), xai, or deepgram. Each backend has its own API key slot. An audio attachment is transcribed whenever the channel can fetch it; if the message also carries a caption, the caption and the transcript are both delivered. See channels.
Streaming	Live reply delivery on chat channels, on by default with the mode derived from the channel: a draft-capable channel (Telegram today) with no streaming key streams in "draft" mode — a live message edited in place that seals into section-shaped cards as it grows — and every other configured channel streams in "block" mode, each completed piece of the model’s output arriving as its own message. "off" disables it per channel. Streaming needs a streaming-capable provider (Codex today; others deliver normally), and background jobs, CLI runs, and scheduled runs never stream. See channels.
Operator	The human owner of a Fermix installation. The operator always resolves to full (:operator) trust, whether arriving via CLI, channel owner_user_id, scheduled job, or voice companion.
Source trust	The trust level (operator or guest) resolved by the ingress layer and carried through the turn into AgentLoop’s capability filter.

Sandbox

Term	Definition
Sandbox	The boundary that enforces filesystem access, command execution, and environment variable passthrough for agent tool calls. Configured by a mode and a command profile. See sandbox.
Mode	The sandbox setting controlling which filesystem subtrees are accessible: strict (the workspace only), standard (the workspace, plus the directory the daemon was launched from, plus the directory an owner’s turn was started from — the latter two only when they sit strictly inside $HOME), or open (all of $HOME). Operator-granted roots are added on top of whichever mode is set.
Command profile	The sandbox setting controlling which preset OS commands are wired as capabilities: bare, assistant, or extended.
Effective roots	The set of filesystem subtrees the sandbox permits for a turn: the mode’s roots plus any operator-granted roots, canonicalized (symlinks resolved) and with blocked_roots and protected paths removed. fermix sandbox explain lists each effective root and marks whether it came from the mode or from an explicit grant.
Protected path	A filesystem location the sandbox refuses to read or write regardless of mode, including system roots, ~/.ssh, and Fermix’s own auth.json.
Grant	An extra filesystem root the operator has explicitly allowed ([sandbox] allowed_roots). Grants are added on top of whatever the mode allows, in every mode, but never override a protected path. Add one with fermix grant path PATH or the owner-only /grant path PATH.
Confirmation token	The single-use, 60-second token Fermix returns when a sandbox change proposed from a chat channel would widen the surface — a looser mode, a new grant, a new command preset, or a new environment passthrough. The owner approves with /confirm TOKEN from the same channel, chat, and sender that proposed it. (The CLI commands apply directly and need no token.) When the agent hits a denied directory during an attended operator turn it can ask for access itself (request_directory_access), showing the canonical path, its reason, and the config diff; on confirmation the grant is saved and the original request resumes. On Telegram and Discord that prompt also carries a one-tap Approve button; it sends the identical confirmation and rides the same single-use, time-limited, origin-bound, owner-only path. Every other surface shows the same prompt as text. In a shared chat on a button channel the code itself is deliberately withheld — approve from the button, a direct message, or the CLI.
Hardline	The sandbox’s first-pass shell-command classifier. It refuses obviously dangerous commands (rm -rf /, shutdown, and similar) regardless of mode or operator grants.
Guest trust	The restricted capability surface granted to non-owner channel senders and plugin-loaded skills. Guest callers may only invoke :read_only policy-class capabilities, and never owner-only capabilities (workspace reads, scheduled-job reads, memory sources).

Memory, prompt, and compaction

Term	Definition
Bootstrap files	Operator-owned files under ~/.fermix/bootstrap/<agent_id>/ that are prepended to every prompt as system context. fermix setup seeds default bootstrap files on first run. See prompt and compaction.
Prompt memory	Facts and summaries promoted from conversation history into persistent memory and reflected into the agent’s prompt on each turn. Stored durably in SQLite; the prompt-memory files (USER.md, MEMORY.md) are derived artifacts.
Compaction	The process of summarizing older messages in a conversation and replacing them with that summary to stay within the model’s context window. Auto-triggered when token usage crosses the configured threshold (default 0.85 of the context window). See prompt and compaction.
Soul / SOUL.md	The agent’s persona file (SOUL.md, a bootstrap file). Owner-curated through the /soul command family, which drafts a bounded persona edit and applies it only after an explicit confirmation; every change is versioned in the Resource registry and revertable.
Resource	A versioned, hash-tracked artifact managed by FermixCore.Resource.Registry. Covers prompt bootstrap files and memory files. Supports diff and rollback for file-backed resources. See resource versioning.

Providers and routing

Term	Definition
Provider	A configured LLM backend. Fermix supports OpenAI (API key), openai_codex (Codex OAuth), Anthropic (API key or subscription OAuth), xAI (API key or Grok OAuth), OpenRouter, Mistral (API key), and a keyless local Ollama. See providers and models.
Primary provider	The provider marked primary = true in its [fermix_core.providers.<name>] block. Exactly one provider is primary, and it handles every turn unless it fails. Setup marks a newly configured provider primary by default; the web setup provider page can flip the primary flag without re-entering credentials (takes effect after a daemon restart).
Fallback chain	Every configured provider other than the primary, tried automatically when the primary fails, in deterministic catalog order (openai_codex, openai, anthropic, xai, openrouter, mistral, ollama). Sub-agents and scheduled jobs can instead be pinned to a specific provider and model.
Adapter	The provider-specific module that implements the chat/3 and continue/3 callbacks. Stateless; provider-specific transcript shape is kept in provider_state.
Reasoning effort	A provider-side hint controlling how much the model deliberates before responding. The canonical vocabulary is none, low, medium, high, xhigh, and max, with per-provider subsets. OpenRouter, Mistral, and Ollama do not accept a reasoning effort field.
Route key	The dispatch tuple %{provider, model, auth_mode, base_url} used to resolve which adapter and options to use for a given turn.

Scheduled jobs and reminders

Term	Definition
Scheduled job	A durable, cron-scheduled agent task. Each run is isolated, bounded by the iteration cap, stored with a result trace, and delivered through the configured channel layer. Jobs can carry an optional expires_at timestamp. See scheduled jobs.
Event (stored date)	A personal date Fermix remembers — a birthday, anniversary, appointment, deadline, or a plain “remind me on Friday” — held as its own durable row rather than as a memory fact, and either one-time or yearly. A yearly event stays one row with one id; its next occurrence is computed by calendar arithmetic, not by adding 365 days. See reminders.
Reminder	One scheduled notification belonging to a stored event, delivered to the configured default background channel. Its text is rendered from the stored event, so no model call happens when it fires — the boundary against a scheduled job, which runs a real agent turn. A failed send retries on the same channel and then fails visibly; Fermix never fails over to another channel.
Reminder plan	The finite set of rules deciding when an event’s reminders fire: for a birthday, 7 days before and on the day; for a timed appointment, 24 hours and 1 hour before. Capped at 10 rules, never a repeating nag, and a plan you ask for replaces the defaults rather than adding to them.
Attended turn	A turn the owner is present for: an interactive chat or CLI message they typed, or a live voice call. Distinct from operator trust, which a scheduled job created by the owner also carries. Storing, changing, cancelling, and snoozing a stored date all require it, so background, delegated, and continuation runs are refused; listing stored dates also works inside a scheduled job the owner created. Two related gates differ: a coding agents tool also accepts a scheduled job that names it in allowed_tools, and request_directory_access needs an operator turn on a channel that can answer /confirm.

Coding agents

Term	Definition
Coding agent run	A background delegation of repository work — reviewing changes, fixing bugs, building features — to the operator’s own Codex or Claude Code CLI, run inside the target repository. Fermix tracks each run under an hr_-prefixed id, delivers its outcome durably, and records it as its own trace. Also called a harness run. See coding agents.
Coding harness	Fermix’s control plane around those vendor CLIs: launch authorization, sandbox admission of the working directory, run artifacts, timeouts, and outcome delivery. It is the same feature the setup page calls “Coding Agents”; fermix doctor reports it under a coding harness row.
Dead-letter	A finished coding run’s outcome message that exhausted its delivery retries. It is kept and surfaced — list_coding_runs groups dead-letter runs separately and fermix doctor warns — rather than dropped.

Observability

Term	Definition
Trace	A structured JSONL record of a single agent turn, tool execution, or provider call. Written to FERMIX_HOME/traces/YYYY-MM-DD/<type>.jsonl by FermixCore.Trace. See traces and telemetry.
Telemetry	:telemetry events emitted by every Fermix component at boundaries where work enters, leaves, blocks, or fails. The telemetry handler bridges these events into durable trace files and optionally into external observability backends.