Getting started
Install Cercano
Source: Cercano/docs/installation-macos.md. This page preserves the current macOS guide, including package caveats. For other systems, use the Linux guide or Windows guide.
Cercano is distributed for Apple Silicon Macs running macOS 12 (Monterey) or later. Intel Macs are not supported by this release.
The formulas are published in the official dedicated
cercano-ai/homebrew-cercano
tap. The personal bryancostanich/homebrew-tap remains separate; its Cercano
formula is deprecated.
Install
brew install cercano-ai/cercano/cercano-agent cercano-ai/cercano/cercano-cli cercano-ai/cercano/cercano
Homebrew 6.0.0 and later only load formulas from a third-party tap that you
have trusted (Tap Trust). Naming a fully
qualified formula trusts only that formula, so installing just
cercano-ai/cercano/cercano stops at its dependencies with "Refusing to load
formula cercano-ai/cercano/cercano-agent from untrusted tap". Naming all three
avoids that. To trust the whole tap instead, including future formulas, run
brew trust cercano-ai/cercano once.
Since v0.27.0, cercano is a dependency-only convenience formula: it installs
cercano-agent and cercano-cli, which own the two commands below. The split was
published in tap commit 0557c9e.
The published definitions still carry fixture/not-release-ready caveats: publication
is not evidence of full runtime or old-monolith migration acceptance. No local
llama/model runtime is bundled.
For component-only installs, use brew install cercano-ai/cercano/cercano-agent
or brew install cercano-ai/cercano/cercano-cli. Neither component depends on
the other; CLI-only use needs a remote agent (cercano-cli --address HOST:PORT).
For a local interactive session, install both with the command above.
Commands installed:
| Binary | Role |
|---|---|
cercano |
the agent, which does the work |
cercano-cli |
the terminal client you interact with |
Start the terminal client:
cercano-cli
The client launches the agent automatically the first time you use it. You do
not need to start cercano yourself, and nothing is installed as a background
service — no launch agent, no daemon, nothing that runs at login. The agent
runs only when you use Cercano.
First run
Cercano ships no models and no credentials. The binaries are self-contained, but on first use you will need to configure at least one of:
- A cloud provider — an API key for your chosen provider.
- A local model — downloaded on demand, which needs disk space and time.
Run cercano-cli and follow the setup prompts. Configuration and conversation
history live in ~/.config/cercano/, outside the Homebrew installation.
Upgrading
For an existing split-package installation:
brew update
brew upgrade cercano-ai/cercano/cercano cercano-ai/cercano/cercano-agent cercano-ai/cercano/cercano-cli
The component names are explicit because the convenience formula owns no binaries and its unversioned dependencies do not promise matching versions or atomic upgrades. For component-only installs, upgrade only the components you use. Check both installed command versions afterwards.
The v0.27.0 split formulas have no post-install restart or service hooks: installation/upgrade does not start, stop, or restart an agent. A running agent may still be the old version; save work and arrange a controlled restart before expecting new behavior. Do not assume the old monolithic formula's automatic restart behavior still applies.
Existing monolithic installs
Before upgrading an older cercano formula that owns both binaries, inspect
brew list --versions cercano cercano-agent cercano-cli, brew list cercano,
and which -a cercano cercano-cli. The old keg can conflict with component
links during dependency-first upgrades. Migration is not yet documented as a
validated automatic path. Preserve your working installation and configuration;
if Homebrew reports conflicts, stop and seek release-specific migration guidance.
Do not force overwrites, remove packages, or delete files to bypass a conflict.
This guide does not prescribe an automatic migration.
PATH conflicts with a development checkout
If you also run Cercano from a source checkout, you may have a development
launcher earlier in your PATH than Homebrew's. Check which one you are
running:
which -a cercano cercano-cli
Homebrew installs to /opt/homebrew/bin. If a development path appears first,
that copy wins, and brew upgrade will not change which binary you run.
The split formulas do not restart either installed or development agents.
Troubleshooting
"cercano" cannot be opened because the developer cannot be verified.
Released binaries are signed with a Developer ID and notarized by Apple, so
this should not happen. If it does, you likely have an unsigned build from
another source. Check the binary path and release provenance before proceeding;
reinstalling the dependency-only cercano formula does not replace component binaries.
The client cannot reach the agent. Confirm nothing else is bound to the
configured port, then start a fresh agent by running cercano-cli again.
The running version did not change. Package upgrades and agent activation are separate. Check command paths and arrange a controlled restart after saving work.
Checking versions. Both binaries report their own version offline:
cercano --version
cercano-cli --version
A client and agent from different versions can still talk to each other; Cercano does not block on a version mismatch. Restarting the agent after an upgrade is still worthwhile so you actually get the new version.
Package ownership and user data
The convenience formula owns no commands; removing it alone does not mean the
component binaries were removed. Configuration and conversations live outside
Homebrew in ~/.config/cercano/; downloaded models are separate too. Do not
remove user data as part of an upgrade or migration.