Docs/Getting started/Quickstart

Quickstart

Install Fermix, connect a channel, and send your first message in a few minutes.

Fermix runs as a local daemon (a background service) on your machine. Once the service is up and a channel is connected, you interact with it through that channel (or the CLI) just like a chat conversation.

Install

brew install tezra-io/tap/fermix

Plugin installation requires cosign to verify plugin signatures (a check that a plugin is genuine and untampered). Install it alongside Fermix:

brew install cosign

For other install methods (build from source, Linux), see installation.

Run setup

fermix setup

fermix setup installs and starts the background service, then opens a one-time setup URL (of the form http://127.0.0.1:4030/setup?t=...) in your browser. On a headless host (a machine with no graphical browser, such as a server) it runs a terminal wizard instead. Pass --cli to force the wizard, or --no-browser to print the URL without opening it.

The setup page covers several surfaces, but three are the essentials to get started:

  1. Provider. Pick a primary LLM provider (OpenAI, OpenAI Codex, Anthropic, SpaceXAI, OpenRouter, Mistral, or a local Ollama) and enter your API key — or, where supported, connect a subscription instead of a key (OpenAI Codex, Claude, and Grok sign in with OAuth). Fermix stores secrets in your OS keychain. See providers and models for the full provider list and fallback chain behavior.

  2. Channel. Connect at least one channel so you have somewhere to talk to the daemon. Telegram is the quickest option: create a bot with BotFather, paste the token, and add your Telegram user ID as the owner. See channels for setup details for WhatsApp, Slack, Discord, and Signal.

  3. Personalization. Set your name, timezone, and communication style, plus the assistant’s own name (leave it blank to keep the default fermix). These shape how the agent addresses you and refers to itself.

The remaining tabs (realtime voice, voice-note transcription, plugins, web search, media, sandbox, memory) are optional and can be configured later — re-run fermix setup any time to reopen the page.

Config is written to ~/.fermix/config.toml. The home directory (FERMIX_HOME) defaults to ~/.fermix.

Confirm the daemon is running

fermix status

Expected output (your pid, version, and uptime will differ):

fermix: running (pid 12345, version x.y.z, up 4s)

If the daemon is not running, start it:

fermix start

Send a first message

From your connected channel, send any message to the bot. Fermix passes it to the main agent and replies in the same conversation.

Alternatively, from the local CLI:

fermix ask "what time is it?"

fermix ask sends one prompt to the running daemon over its local control connection and prints the reply. It does not require a channel to be configured.

Give a standing instruction

Tell the agent directly in conversation and it will store the fact in memory:

Remember: always respond in British English

The agent uses the memory_store tool to persist this. Fermix periodically rebuilds a USER.md profile from stored facts (a background “dreaming” review runs roughly every 24 hours) and injects it into every agent turn. You do not need to edit any file directly. See memory for how memory works and how it flows into prompts.

Run a request in the background

Prefix any message with /background to run it as detached work. The agent acknowledges immediately and keeps the conversation free — you can keep chatting (or close the chat) while the work runs, and the result is posted back to the same conversation when it finishes.

/background research the top five open-source vector databases and summarize their license terms

Check on background work started from this conversation:

/tasks

Cancel all in-flight work, including background tasks:

/stop

These are owner-only slash commands — they work for the owner user ID you set during setup. Background work runs inside the daemon’s memory and is not persisted: if the daemon restarts mid-run, the work is lost and you start it again. For work that must survive restarts or run on a schedule (digests, watchers, reminders), use scheduled jobs — those are stored durably and their results are delivered even across restarts. /stop does not affect scheduled jobs or voice sessions.

Check daemon status

fermix status

For a structured readiness report including provider status, per-channel status, and memory backend status, hit the health endpoint:

curl http://127.0.0.1:4030/health/ready

Tail the log:

fermix logs -f

If something looks wrong, run the built-in diagnostics:

fermix doctor

fermix doctor prints one OK/WARN/FAIL line per check — provider configuration, service unit, sandbox, stale OAuth tokens that need a reconnect, and more. Add --full for network checks such as a live provider auth probe.

What’s next

Topic Link
Channel setup details (Telegram, WhatsApp, Slack, Discord, Signal) channels
Provider and model selection, fallback chain providers and models
Plugins: bundled Google integrations plus installable ones (Slack, Discord, and more) plugins
Slash commands available in chat (/help, /compact, /new, …) commands
Scheduled background jobs (digests, watchers, reminders) scheduled-jobs
Full CLI command reference cli-reference
Architecture overview architecture
All built-in tools tool-reference

Next steps

Architecture How Fermix is structured: the five internal apps that make up the single binary, the path a message takes from arrival to reply, who is trusted to do what, and where data is stored on disk.Channels How Fermix handles messages from Telegram, WhatsApp, Slack, Discord, Signal, and the local CLI through one common path to the agent, and the slash commands available in every channel.Providers and models How Fermix picks which AI provider and model to use, switches to a backup when one fails, and lets you set the model, how hard it thinks, and per-route overrides.