Installation
This document describes how to install Opair, and how to upgrade or uninstall it afterwards.
Platforms
macOS and Linux, on amd64 and arm64. Windows is not supported. Some of the file system handling is POSIX-specific and does not work there.
Homebrew (macOS)
brew tap philbooth/opair
brew trust philbooth/opair
brew install --cask opair
The cask is signed and notarized, so Gatekeeper has nothing to complain about.
The install puts the opair binary on your $PATH
and copies the example configs
and the tools/, loops/, prompts/ and mcp/ directories
into your config directory:
$XDG_CONFIG_HOME/opair if set,
otherwise ~/Library/Application Support/opair.
Upgrading
brew upgrade --cask opair
An upgrade overwrites the example configs
and the asset directories in your config directory.
Your config.json is not touched.
If you have customised the assets,
point OPAIR_TOOLS_DIR and friends somewhere else first,
or your edits will be quietly replaced.
See environment variables.
Uninstalling
brew uninstall --cask opair
Homebrew leaves the config directory alone.
Packages (Linux)
Releases publish .deb and .rpm packages
for amd64 and arm64.
Download the one that matches your distribution and architecture
from the releases page.
The exact file names are on that page.
For Debian, Ubuntu and derivatives:
sudo apt install ./opair_{version}_{arch}.deb
For Fedora, RHEL, openSUSE and derivatives:
sudo dnf install ./opair-{version}.{arch}.rpm
The package installs the binary to /usr/bin/opair
and the canonical assets to /usr/share/opair.
A postinstall script then seeds your config directory
($XDG_CONFIG_HOME/opair if set,
otherwise ~/.config/opair)
with the example configs and the asset directories.
If the postinstall script runs as root with no way to tell which user invoked the package manager, it writes nothing and prints instructions for finishing the setup by hand. This is normal under CI and unattended upgrades.
Upgrading
Download the new package
and install it over the old one.
Your config.json is never overwritten.
The example configs and the asset directories are.
Uninstalling
sudo apt remove opair
or:
sudo dnf remove opair
The package manager removes /usr/bin/opair
and /usr/share/opair.
Your config directory is left in place.
Manual download
Releases publish a zip for macOS
and a checksums.txt.
Linux users should prefer the packages.
Download opair_{version}_darwin_{arch}.zip
and checksums.txt from the
releases page,
then check the checksum:
shasum -a 256 opair_{version}_darwin_{arch}.zip
The output should match
the corresponding line in checksums.txt.
Unzip the archive.
It contains the opair binary,
the example configs and the asset directories.
Move the binary somewhere on your $PATH,
then copy the rest into your config directory.
From the extracted directory:
mkdir -p ~/Library/Application\ Support/opair
cp config.*.json ~/Library/Application\ Support/opair/
cp -R loops mcp prompts tools ~/Library/Application\ Support/opair/
If XDG_CONFIG_HOME is set,
use $XDG_CONFIG_HOME/opair instead.
To upgrade,
download the new zip and repeat.
Installing from source
You need Go 1.27 or later and a checkout of the repository:
git clone https://gitlab.com/philbooth/opair.git
cd opair
The install scripts build Opair with go install
and seed your config directory:
# Anthropic setup:
scripts/install-anthropic.sh
# OpenAI setup:
scripts/install-openai.sh
# Deepseek setup:
scripts/install-deepseek.sh
# Z.ai setup:
scripts/install-zai.sh
# llama.cpp setup:
scripts/install-llamacpp.sh
# Enablers setup (Algolia employees only):
scripts/install-algolia.sh
Each script writes its provider's example config
to config.json.
Re-running a script resets config.json
to that provider's example;
your edits go with it.
To build without the config setup:
make build
That produces ./opair in the repo root
and does nothing else.
You will have to create the config directory yourself.
See the configuration doc.
Upgrading
Pull the latest changes
and re-run whichever script you used,
or go install ./cmd/opair again.
The scripts overwrite the asset directories
and, as noted, config.json.
Uninstalling
Delete the binary
(go clean -i ./cmd/opair does it)
and the config directory if you want:
rm -rf ~/.config/opair
On macOS the config directory is
~/Library/Application Support/opair,
unless XDG_CONFIG_HOME is set.
After installing
Opair must be configured before first use.
Most of the methods above seed a config.json for you.
See the configuration doc
for what goes in it
and which environment variables hold your API keys.