# macOS app

> Install and set up the Fermix macOS app, manage its background service, move an existing Homebrew install, and use the bundled CLI.

The Fermix app brings setup, settings, daemon status, Doctor, logs, and the voice companion into one macOS application. It includes the Fermix engine and runs it as a background service. macOS 15 Sequoia or newer is required; Apple Silicon and Intel Macs are supported.

## Install

**Already using the Homebrew formula?** Follow [Move from the Homebrew formula](#move-from-the-homebrew-formula) before installing the app. Installing the cask beside the formula does not migrate its service.

For a fresh install:

```bash
brew install --cask tezra-io/tap/fermix
```

Or download the signed, notarized DMG from the [macOS releases](https://github.com/tezra-io/fermix-macos/releases), drag the app into Applications, and open Fermix. Keep one copy in Applications; the app refuses to take over a home when duplicate copies or another daemon are present.

## First setup

1. Open Fermix and choose **Set up Fermix**. It registers the background service and waits for the daemon to answer. If macOS asks for background-item approval, allow Fermix in System Settings under Login Items.
2. **Connect your AI** with a supported existing sign-in, a browser sign-in, or an API key. The first provider you connect becomes primary. An existing configured provider is preserved.
3. Under **About you**, enter your name, time zone, and communication style. You can also name the assistant.
4. Let Fermix apply the answers and restart. Once it reports **Fermix is live**, connect channels or enable [realtime voice](/docs/realtime-voice) when needed.

A configured provider and those three personalisation answers complete required setup. An enabled channel missing credentials, or voice missing an OpenAI key, appears as an issue to fix without blocking the rest of setup.

The default data folder is `~/.fermix`. Choose **Use an existing Fermix home…** during setup to select another folder, or let the migration command carry it over. The app, background service, and bundled CLI use the home recorded in `~/Library/Application Support/Fermix/launcher.json`; the app does not read shell `FERMIX_HOME` or `FERMIX_REALTIME_SOCKET` overrides.

For a DMG install, **Install the fermix command for Terminal** offers a command to copy and run yourself, then **Check again** verifies the link. The app does not replace an existing file at that location. A Homebrew cask owns its own command link.

## Background service and windows

| Control | Effect |
|---------|--------|
| **Run in the background**, or **Enable Background Service** / **Disable Background Service** in the Daemon menu | Register or unregister the daemon's background service. |
| **Open at login** | Open the graphical app at login, independently of the daemon. |
| **Show Fermix in the menu bar** | Show or hide the app's menu bar item. |
| **Restart Fermix…** | Show pending changes and work a restart would interrupt, then restart after confirmation. |
| **Quit Fermix** | Close the app and its voice call. The enabled background service keeps running. |

Closing a window or hiding the floating companion also leaves the daemon running. To stop background operation, disable the background service.

## Settings and diagnostics

Settings covers providers, personality, memory, channels, integrations, voice, meetings, computer use, coding agents, search, images, sandbox, and permissions. The app and browser setup share the daemon's settings, validation, and secret storage. Saved secrets are shown only as present or absent. Sign-ins and installs show progress and can be cancelled.

Changes that need a restart are identified in the app. If another editor changes `config.toml`, saving pauses until you choose **Reload settings from disk**. Repair an unreadable file first; reloading is not a substitute for fixing a parse error. Reloading settings can still leave a restart pending.

**Home** shows status and items needing attention. **Doctor** runs local checks or optional network checks and exports a support bundle. Network checks can make metered provider calls. **Logs** follows the daemon while visible and supports pausing, copying, and exporting entries. **Pet** opens the voice companion; microphone access is requested when you begin a call.

## CLI behavior

The CLI bundled with the app follows these rules:

| Command | App-managed behavior |
|---------|----------------------|
| `fermix start`, `fermix stop`, `fermix service install`, `fermix service uninstall` | Refuse and point to the app's background-service controls. |
| `fermix restart` | Restart the daemon and verify that a new process answers, preserving the service registration. |
| `fermix setup` | Open the app's setup assistant or settings. Terminal setup flags do not run a separate wizard. |
| `fermix upgrade` | Open the app's update guidance. A successful exit confirms the handoff, not an installed update. |
| `fermix uninstall` | Open Doctor with removal guidance. There is no built-in uninstall action; the command removes nothing. |
| `fermix status`, `fermix doctor`, `fermix logs` | Read the daemon over its local management socket. |

`fermix logs -n N` accepts 1–500 entries on the app's CLI. `-f` is refused; use the app's Logs screen. Doctor marks **upgrade**, **binary integrity**, and **service unit** as not applicable because the app owns its engine and service.

A standalone CLI pointed at an app-managed home also refuses `start`, `stop`, and `service install`, and routes `setup` and `upgrade` to the app. Its `service uninstall` remains available to remove a legacy standalone service.

## Move from the Homebrew formula

Run the migration from the shell that knows your existing `FERMIX_HOME`. First confirm that Homebrew can find the app cask:

```bash
brew info --cask tezra-io/tap/fermix
```

If it reports that the cask is unavailable, stop here and keep the formula installed. Migration uninstalls the formula before installing the cask.

Once the cask is available, update the formula and restart the daemon so it can answer the management protocol:

```bash
brew upgrade tezra-io/tap/fermix
fermix restart
fermix migrate-to-app
```

The last command only inspects the install and prints a plan; it changes nothing and exits `2`. Review the recorded home and service, then run:

```bash
fermix migrate-to-app --yes
```

It drains the daemon, stops and removes the verified user launch agent, records the home in a handoff journal, uninstalls the formula, installs the cask, and opens the app. Finish onboarding in the app, which adopts the same home. Your configuration, memory, and other home data are preserved.

The command refuses an existing app installation, duplicate app copies, a system-wide service, an unrecognised launch agent, a running `brew services` entry, or an unrelated `fermix` on `PATH`. Follow the specific remedy it prints. A failed command stops the migration; if a Homebrew step fails, follow the reported recovery instructions before retrying. Do not replace this process with `brew uninstall fermix`: the formula does not own the launch agent that standalone setup installed.

## Update the app

For a cask install, run `brew upgrade --cask tezra-io/tap/fermix`. For a DMG install, replace the application with the newer signed download. Reopen Fermix and apply any restart it requests so the new engine is running.

Automatic update checks and built-in removal are not available. `fermix upgrade` opens guidance; it does not overwrite a binary inside the signed app bundle. Standalone installs retain their own [upgrade workflow](/docs/distribution-and-upgrade).