Installation

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 for details.

Homebrew (macOS and Linux)

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 releases. See 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 also uses cosign to verify a downloaded release binary before swapping it in, and refuses to proceed if cosign is missing.

Install cosign:

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 attaches one self-contained binary per platform, named fermix_<os>_<arch> (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:

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.

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 (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.

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 for available options.

Next step

Once the binary is installed, run:

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 for the full walkthrough, including non-interactive flags for scripted installs.

Upgrade

For Homebrew installs, use Homebrew to upgrade:

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 for the full upgrade reference.