Plugins

A plugin is a connected integration that owns an external surface — an API, a vault, a SaaS account — and registers its own tools into Fermix’s capability registry. Each tool a plugin contributes is named <plugin>_<tool> (for example gmail_send_message or slack_list_channels), so tools from different plugins cannot collide and the agent can see at a glance which surface a tool belongs to. Once a plugin is connected, the agent prefers its tools over the generic browser/web_fetch/shell capabilities for that surface.

Bundled plugins

Three plugins are always present and cannot be uninstalled (you disable them instead):

• Gmail
• Google Calendar
• Google Drive

All three authenticate through Google OAuth. They follow a graceful-403 model: a connected plugin registers all of its tools regardless of which OAuth scopes you granted. If you call a tool whose scope was not granted, you get a clear “reauthorize” error telling you to reconnect with the missing scope — the tool does not silently vanish from the agent’s view. Other Google 403s are classified distinctly (file-permission, organizer-only, rate-limit) so the error message says what actually failed instead of collapsing every denial into one generic auth error.

Where additional plugins come from

Beyond the bundled trio, plugins come from a signed catalog bundled inside the Fermix binary. This is the only catalog source — there is no remote index and no runtime refresh. New and updated plugins reach you with the next Fermix release, so you get them by running fermix upgrade (see distribution and upgrade).

Which plugins exist, and at which versions, is a moving target that this page deliberately does not duplicate. Run fermix plugins catalog to see what the binary you are running actually offers, and browse tezra-io/fermix-plugins for the source each one is built from.

Installing a plugin streams its tarball, verifies the artifact against the catalog’s recorded sha256 hash and a cosign signature, and re-validates the decoded manifest before activating it into a versioned store under $FERMIX_HOME/plugins/. The guarantee is simple: a plugin that installs will load. (Cosign verification needs the cosign binary on the daemon’s PATH; a genuinely missing one is refused with an install hint, while one that exists but is not on the supervised daemon’s PATH can surface as a misleading signature error — see distribution and upgrade.)

The catalog currently ships:

Plugin	What it does	Rail	Auth
GitHub	Work with repositories, issues, and pull requests.	HTTP	OAuth
Notion	Search, read, create, and update pages and data sources.	HTTP	OAuth
X	Post, reply, search, like, and read on X (Twitter).	HTTP	OAuth
Slack	Read channels, messages, threads, and members.	HTTP	api_key
Discord	Read servers, channels, messages, and members.	HTTP	api_key
AgentMail	Create agent-owned email inboxes; send, read, and reply to mail.	HTTP	api_key
Obsidian	Search, read, create, and append to notes in your local Obsidian vault.	MCP	none
Computer Use (computer_use_sidecar)	The native helper binary behind the computer-use capability — a setup card, not a tool set, and not managed by fermix plugins (see below).	—	none

One catalog entry is special. Computer Use (computer_use_sidecar) is not a tool-registering plugin: it is the native helper binary behind the experimental, off-by-default computer-use capability (see capabilities and tools). It runs on Apple Silicon (M-series) macOS and Linux x86_64 only — on an Intel Mac the download fails with a clear “no build for this machine” error.

It is also the one entry that does not go through the signed-tarball pipeline above, and fermix plugins does not manage it. The helper is fetched from the compux project’s own signed release and verified against a SHA-256 checksum baked into your Fermix build, then cached under ~/.fermix/plugins/compux/. Enabling its card on the setup Plugins page does both halves — downloads the helper and flips [fermix_core.computer_use] enabled — and both are needed, with the change applying on the next daemon restart.

You only do that once. After that, a daemon that has computer use enabled but is missing the helper matching its build — the state an upgrade lands in when a new release pins a newer helper — downloads it itself on its next start. That happens on daemon boot only, is bounded to about thirty seconds, and fails soft: if the download does not land, computer use simply stays off until the next restart or until you use the setup card again.

The two rails

Every tool-registering catalog plugin runs on one of two execution rails (the Computer Use helper, which registers no tools, is the one entry with neither).

HTTP rail

An http plugin is a set of declarative request templates that run in-VM — Fermix makes the HTTP calls itself, no external process. The rail is double-guarded:

• Install time: the templates are validated, and every endpoint must be https:// with no placeholder or userinfo (user:pass@) host.
• Runtime: an SSRF floor blocks requests to loopback, private, and cloud-metadata addresses, so a template can never be steered at an internal host.

Responses are guarded too: only JSON is accepted, bodies are capped at 5 MiB, and multi-page listings are fetched through bounded pagination — large downloads belong on the MCP rail.

MCP rail

An mcp plugin is a supervised local process the daemon launches and monitors. On connect Fermix discovers the process’s tools and registers them as <plugin>_<tool>, exactly like the HTTP rail. Installing an mcp plugin first probes the host runtime its manifest declares (a Node or Python interpreter, or a vendored standalone binary); a missing or too-old runtime is refused with a missing_host_runtime status rather than a broken install.

Supervision is bounded, not infinite. A server that fails tool discovery is retried with exponential backoff — up to five attempts in total; if it never answers, it gives up terminally and is quarantined: the process tree is torn down and its tools stay unregistered instead of respawning forever. A genuine transport blip still reconnects on its own. Enabling or disabling a plugin asks the running daemon to re-apply its configuration, which starts a quarantined server fresh — as does restarting the daemon with fermix restart.

This rail is plugin-managed and distinct from the manually-configured [mcp.servers] blocks documented in inbound and outbound MCP — those are MCP servers you wire up by hand in config.toml; plugin mcp processes are installed and supervised through the plugin system.

Authentication

An HTTP-rail plugin authenticates one of two ways. Either way, the credential is injected using the scheme the plugin’s manifest declares for the Authorization header — Bearer by default, or another scheme such as Bot for a provider like Discord. (A plugin that needs no credential at all — like Obsidian, whose process reads a local vault — declares auth none and is ready as soon as it is enabled.)

Auth mode	How you connect	Not-ready status
OAuth	An OAuth provider client configured under [fermix_core.oauth.<provider>] (client id + secret), then fermix plugins auth login NAME — logging in also enables the plugin.	needs_client_config until the client is configured, then needs_auth until connected.
api_key	A static secret the operator sets with fermix plugins auth set NAME VALUE — stored in the OS keychain, never plaintext config.	needs_secret until set.

In today’s catalog, GitHub, Notion, and X connect over OAuth; Slack, Discord, and AgentMail use an api_key (a bot token or API key you create with that service). For more on how OAuth clients and keychained secrets are stored, see auth and secrets.

When a credential stops working

A failing credential reaches the agent as a named, actionable tool error — never a bare status code — so it can tell you the exact fix (or, for an operator, run it):

• OAuth token rejected (HTTP 401): “<plugin> needs reconnection. Run fermix plugins auth reauthorize <plugin>.”
• API key rejected: “API key rejected — update it with fermix plugins auth set <plugin>” (a missing key points at the same command).
• Enabled but never connected: “<plugin> is enabled but not connected. Run fermix plugins auth login <plugin>.”

On an OAuth 401 Fermix first attempts one silent token refresh and retry — but only for tools the manifest marks read-only. A write that comes back 401 is never blindly retried; it surfaces the reauthorize error immediately.

Tokens can also go stale from disuse, without any tool call failing: a token well past its expiry is flagged before next use — as a Reconnect needed badge on the setup page and in fermix doctor’s auth tokens check (see auth and secrets).

Readiness states

When a plugin is enabled but not yet ready to use, the agent sees a status= marker in its prompt instead of the tool simply disappearing — so it can tell you what to fix rather than failing blindly:

Status	Meaning	Fix
needs_client_config	An OAuth plugin whose provider client (client id + secret under [fermix_core.oauth.<provider>]) is not set up.	Configure the OAuth client on the setup page.
needs_auth	An OAuth plugin that has not been connected.	fermix plugins auth login NAME (or connect it on the setup page).
reauthorization_required	An OAuth plugin whose stored token was invalidated by the provider.	fermix plugins auth reauthorize NAME.
needs_secret	An api_key plugin with no secret set.	fermix plugins auth set NAME VALUE.
needs_config	A manifest-declared config value is missing.	fermix plugins config set NAME KEY VALUE.
missing_host_runtime	An mcp plugin whose host runtime is missing or too old.	Install or upgrade the runtime, then fermix plugins doctor NAME.
not_installed	A catalog plugin that is enabled but not installed locally.	fermix plugins install NAME (or enable auto-installs it).
incompatible	An installed version outside the running Fermix’s compatibility window (typically after fermix upgrade).	fermix plugins upgrade NAME, or upgrade Fermix.

How the agent discovers plugins

The agent learns what is live from the ## Plugins section of its runtime prompt. There is no agent tool that lists plugins — a ready plugin’s tool names are listed in that prompt section, and the agent calls them directly (with schemas resolved on demand through tool-schema deferral; see capabilities and tools). An enabled-but-not-ready plugin shows its status= there instead, which signals “not connected” — so the agent offers to connect it on the setup page rather than scraping the surface another way.

To inspect things yourself: fermix plugins list shows each plugin’s status and connected account, and fermix plugins installed shows the local store. Note that fermix plugins catalog lists the plugins the registry already knows about (bundled, installed, and dev-local) — the full catalog, including plugins you have not installed yet, is shown on the web setup Plugins page. Enable, disable, and logout take effect on the agent’s next turn (the reload drops cached runtime context — no daemon restart needed), and calling a disabled plugin’s tool refuses with an enable hint rather than a generic auth error.

Operator commands

The fermix plugins command group manages the whole lifecycle. The full signatures live in the CLI reference; the key verbs are:

• Inspect: list, catalog, installed, doctor, auth status [NAME]
• Toggle: enable, disable, reload
• Manage the local store: install, upgrade, pin, uninstall, gc
• OAuth auth: auth login NAME, auth reauthorize NAME, auth refresh NAME, auth logout NAME
• api_key auth: auth set NAME VALUE, auth clear NAME
• Per-plugin config: config NAME (shows declared keys and values), config set NAME KEY VALUE (sets manifest-declared [fermix_core.plugins.<name>] values)

The web setup Plugins page renders the full catalog: install-on-connect cards that verify sha256 + cosign, with OAuth client id/secret entered through a per-provider modal. (The one exception is the Computer Use card, which installs the native helper via the sha256-verified download described above and shows readiness from the computer-use feature itself — “Ready” or “Needs setup”.)

For plugin authors

To develop a plugin without an install or tarball step, point Fermix at a local directory:

[fermix_core.plugins]
dev_local = "/path/to/fermix-plugins/plugins"

The path’s immediate subdirectories are treated as plugin directories (for a fermix-plugins checkout, that is its plugins/ directory). They load into the registry like installed plugins — full manifest validation, skills loaded in place — with no signing or packaging. A missing or unreadable path, a bad manifest, or a name that collides with a bundled or installed plugin fails plugin loading loudly rather than being skipped.