# Installation > How to install Fermix on macOS or Linux — via the Homebrew tap, a direct binary download, or building from source. Fermix ships as a single self-contained program. Installing it puts one executable on your `PATH`; everything else lives under `~/.fermix` (overridable with `FERMIX_HOME`). After installation, run `fermix setup` to configure the daemon (the background service that keeps Fermix running) and channels. See [setup](/docs/setup) for details. ## Homebrew (macOS and Linux) ```bash brew install tezra-io/tap/fermix ``` This installs the `fermix` binary from the `tezra-io/tap` tap. Homebrew handles dependency resolution and future upgrades via `brew upgrade tezra-io/tap/fermix`. The optional macOS voice companion app, FermixPet, is installed separately — `brew install --cask tezra-io/tap/fermixpet`, or the notarized DMG from the [tezra-io/fermix-macos](https://github.com/tezra-io/fermix-macos) releases. See [realtime voice](/docs/realtime-voice). ### cosign requirement Fermix checks every plugin's cryptographic signature (proof it came from a trusted source and was not tampered with) before activating it. The daemon runs `cosign verify-blob` and refuses any plugin whose signature does not check out. If `cosign` is not on the daemon's `PATH`, plugin installation fails. [`fermix upgrade`](#upgrade) also uses `cosign` to verify a downloaded release binary before swapping it in, and refuses to proceed if `cosign` is missing. Install cosign: ```bash brew install cosign ``` The `fermix service install` command pins a `PATH` in the generated service unit (the OS file that defines how the background service starts, launchd on macOS, systemd on Linux) that includes the directory where `fermix` itself was installed, so `cosign` installed in the same Homebrew prefix is found by the daemon without manual configuration. One exception: the experimental computer-use helper (off by default) is not delivered as a signed plugin tarball. Enabling it downloads a native helper binary that Fermix verifies against a `sha256` checksum built into the release, so `cosign` is not involved in that download. ## Direct binary download Every [GitHub release](https://github.com/tezra-io/fermix/releases) attaches one self-contained binary per platform, named `fermix__` (for example `fermix_macos_aarch64`), plus a `releases.json` manifest listing each artifact's `sha256` checksum and signature files. Download the binary for your platform, check its `sha256` against the manifest, and put it on your `PATH`: ```bash curl -fsSLO https://github.com/tezra-io/fermix/releases/latest/download/fermix_macos_aarch64 shasum -a 256 fermix_macos_aarch64 # compare against releases.json sudo install -m 0755 fermix_macos_aarch64 /usr/local/bin/fermix fermix setup ``` Binaries installed this way are unmanaged, so they can later update themselves with [`fermix upgrade`](#upgrade). ## What gets installed After installation the binary is on your `PATH`. No other files are created until you run `fermix setup`, which (together with the daemon it starts) writes the following layout: | Path | Purpose | |------|---------| | `~/.fermix/config.toml` | Runtime configuration | | `~/.fermix/workspace/` | Sandbox workspace root | | `~/.fermix/grants/` | Sandbox grants | | `~/.fermix/bootstrap/` | Prompt files seeded by setup (identity, persona, runtime instructions) | | `~/.fermix/memory/` | Prompt profiles rebuilt from memory (`USER.md`, `MEMORY.md`) | | `~/.fermix/daemon.sock` | Control socket the CLI talks to | | `~/.fermix/realtime.sock` | Realtime voice companion socket | | `~/.fermix/skills/` | User-installed skills | | `~/.fermix/browser/` | Browser tool profiles | | `~/.fermix/journals/` | Agent journal storage | | `~/.fermix/realtime/` | Realtime voice session data | | `~/.fermix/traces/` | Structured JSONL traces | | `~/.fermix/logs/` | Rotating daemon log (10 MB × 5 files by default) | | `~/.fermix/memory.db` | SQLite memory database | | `~/.fermix/plugins/` | Installed plugin store | | `~/.fermix/setup-token` | Durable local secret gating the web setup UI (never appears in URLs) | | `~/.fermix/auth.json` | OAuth token store (created on first OAuth login, any provider) | | `~/.fermix/.previous` | Snapshot of the previous binary (used for rollback during self-upgrade) | | `~/.fermix/upgrades.jsonl` | Audit log of every upgrade attempt | Set `FERMIX_HOME` to override the root directory for all of the above. ## Supported platforms Fermix releases provide pre-built binaries for: | Target | Notes | |--------|-------| | `macos_aarch64` | Apple Silicon | | `macos_x86_64` | Intel Mac | | `linux_aarch64` | | | `linux_x86_64` | | Windows is not supported. One capability has narrower platform support than Fermix itself: the experimental computer-use helper (off by default) is available only on Apple Silicon macOS and Linux `x86_64` — installing it on an Intel Mac fails with a clear error. ## Build from source Building from source requires Elixir, Erlang/OTP, and [Zig](https://ziglang.org) (Burrito uses it to package the self-contained binary). Rather than pin versions here — where they go stale silently — take them from the repository itself, which is what CI builds against: the Elixir and OTP floors are the `elixir:` and `:extra_applications` requirements in each app's `mix.exs`, and the Zig version is `ZIG_VERSION` in [`.github/workflows/release.yml`](https://github.com/tezra-io/fermix/blob/main/.github/workflows/release.yml). ```bash git clone https://github.com/tezra-io/fermix.git cd fermix mix deps.get MIX_ENV=prod mix assets.deploy BURRITO_TARGET=macos_aarch64 MIX_ENV=prod mix release fermix --overwrite sudo install -m 0755 burrito_out/fermix_macos_aarch64 /usr/local/bin/fermix fermix setup ``` Replace `macos_aarch64` with the appropriate target (`macos_x86_64`, `linux_aarch64`, `linux_x86_64`). Omit `BURRITO_TARGET` to build all four targets. For development without packaging a binary, use `mix fermix.dev` instead of running a release. See the [CLI reference](/docs/cli-reference) for available options. ## Next step Once the binary is installed, run: ```bash fermix setup ``` `fermix setup` installs and starts the background service, then opens `http://127.0.0.1:4030/setup` in your browser to complete configuration (the printed link carries a short-lived, one-time login token). On a headless host it runs a terminal wizard instead. See [setup](/docs/setup) for the full walkthrough, including non-interactive flags for scripted installs. ## Upgrade For Homebrew installs, use Homebrew to upgrade: ```bash brew upgrade tezra-io/tap/fermix ``` A package-manager upgrade only swaps the binary on disk — the background daemon keeps running the old version until you run `fermix restart`. `fermix status` and `fermix doctor` warn while the running daemon's version differs from the installed binary. Running `fermix upgrade` on a package-manager install (Homebrew or dpkg) is refused: the command detects the package manager and prints the correct `brew upgrade` / `apt upgrade` command instead. Run `fermix upgrade --check` to see the installed version, the latest release, and how your install is managed, without changing anything. For unmanaged installs (a directly downloaded or source-built binary), `fermix upgrade` handles the full cycle: it fetches the release manifest from GitHub, downloads the new binary together with its signature files, verifies the `sha256` checksum and the cosign signature (with the signing identity bound to the exact release tag — this step needs `cosign` on your `PATH`), snapshots the running binary to `~/.fermix/.previous`, swaps the binary in one atomic step, restarts the service, polls the daemon over its local control socket for up to 10 seconds, and rolls back automatically if that health check fails. Every attempt is recorded in `~/.fermix/upgrades.jsonl`. If the service unit drifted across the upgrade (for example an updated `PATH` or template), re-run `fermix setup` rather than `fermix restart` — it rewrites and reloads the unit, which a plain restart never does. See [distribution and upgrade](/docs/distribution-and-upgrade) for the full upgrade reference.