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: http (declarative request templates executed in-VM, https-only behind an SSRF floor) or mcp (a supervised local process whose discovered tools register as <plugin>_<tool>).
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.
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.
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.
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 messaging integration through which users reach the agent: Telegram, WhatsApp, Slack, Discord, Signal, or the local CLI. All channels normalize inbound messages and dispatch through MainAgent. See channels.
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.
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.

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

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.

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.