# 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

```bash
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:

```bash
brew install cosign
```

For other install methods (build from source, Linux), see [installation](/docs/installation).

## Run setup

```bash
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](/docs/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](/docs/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

```bash
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:

```bash
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:

```bash
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](/docs/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](/docs/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

```bash
fermix status
```

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

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

Tail the log:

```bash
fermix logs -f
```

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

```bash
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](/docs/channels) |
| Provider and model selection, fallback chain | [providers and models](/docs/providers-and-models) |
| Plugins: bundled Google integrations plus installable ones (Slack, Discord, and more) | [plugins](/docs/plugins) |
| Slash commands available in chat (`/help`, `/compact`, `/new`, ...) | [commands](/docs/commands) |
| Scheduled background jobs (digests, watchers, reminders) | [scheduled-jobs](/docs/scheduled-jobs) |
| Full CLI command reference | [cli-reference](/docs/cli-reference) |
| Architecture overview | [architecture](/docs/architecture) |
| All built-in tools | [tool-reference](/docs/tool-reference) |