macOS

Flavor runs on macOS, on Intel and Apple Silicon. It has been tested on macOS 15. You get the same daemon (flavord), CLI (flavorctl) and desktop app as on Linux, with one exception: system-wide names need the Linux-only flavor-netd helper. To reach services without it, use port forwarding or the SOCKS5 proxy.

Note

The macOS builds are not signed with an Apple Developer ID or notarized yet. They are ad-hoc signed, so Gatekeeper blocks them when they come from Homebrew or a browser download. Opening an unsigned build shows how to allow them.

Install with Homebrew

brew tap tame-gg/tap
brew trust tame-gg/tap
brew install flavor
brew services start flavor
brew install --cask flavor-desktop

brew trust is only needed on Homebrew 6 and newer. The formula installs flavord and flavorctl; brew services runs flavord at login as the LaunchAgent sh.brew.flavor, logging to $(brew --prefix)/var/log/flavord.log. The cask installs Flavor.app into /Applications. macOS blocks its first launch: see Opening an unsigned build.

brew services restart flavor
brew upgrade flavor flavor-desktop && brew services restart flavor
brew services stop flavor && brew uninstall --cask flavor-desktop && brew uninstall flavor

These are, in order: restart the daemon, upgrade, and uninstall. Uninstalling keeps your data in ~/Library/Application Support/flavor.

If you installed from the tarball before, remove that LaunchAgent and the old binaries first, as in Uninstall. Your networks carry over. The sections Running the daemon, Upgrade and Uninstall below are for the tarball install.

Install from the tarball

Each release has a tarball per architecture: darwin-arm64 for Apple Silicon and darwin-amd64 for Intel. Run uname -m if you're unsure: arm64 means Apple Silicon. Each tarball contains:

• bin/flavord and bin/flavorctl
• Flavor.app
• launchd/dev.lunarlabs.flavor.flavord.plist, the LaunchAgent that starts flavord at login

v=0.1.0-beta.7
arch=arm64
base=https://github.com/tame-gg/Flavor/releases/download/v$v
curl -fLO $base/flavor-$v-darwin-$arch.tar.gz -fLO $base/SHA256SUMS -fLO $base/SHA256SUMS.asc -fLO $base/SHA256SUMS.sigstore.json
shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf flavor-$v-darwin-$arch.tar.gz
cd flavor-$v-darwin-$arch

Verify the download works the same as on Linux, using shasum -a 256 instead of sha256sum.

Install the daemon and CLI into your home directory, and the app into ~/Applications. None of this needs sudo:

mkdir -p ~/.local/bin ~/Applications ~/Library/LaunchAgents
cp bin/flavord bin/flavorctl ~/.local/bin/
cp -R Flavor.app ~/Applications/
sed "s|@HOME@|$HOME|g" launchd/dev.lunarlabs.flavor.flavord.plist > ~/Library/LaunchAgents/dev.lunarlabs.flavor.flavord.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.lunarlabs.flavor.flavord.plist
~/.local/bin/flavorctl info

Add ~/.local/bin to your PATH if you want to type flavorctl without the full path. Then open Flavor from ~/Applications and continue with Getting started.

Opening an unsigned build

A tarball downloaded with curl and extracted with tar has no quarantine flag, so it opens directly. If you installed it with Homebrew or downloaded it in a browser, macOS refuses to open Flavor the first time. Allow it in one of two ways:

• Try to open Flavor once, then go to System Settings › Privacy & Security and click Open Anyway next to the message about Flavor.

• Or remove the quarantine flag in Terminal:

  xattr -dr com.apple.quarantine ~/Applications/Flavor.app ~/.local/bin/flavord ~/.local/bin/flavorctl

  With Homebrew, the app is in /Applications:

  xattr -dr com.apple.quarantine /Applications/Flavor.app

Only do this for a download whose checksum and signature you verified.

Where Flavor keeps its files

What	Where
Database, network identities, desktop settings	~/Library/Application Support/flavor
Daemon socket and lock	~/Library/Application Support/flavor (flavord.sock, flavord.lock)
Daemon log	~/Library/Logs/flavord.log, or $(brew --prefix)/var/log/flavord.log with Homebrew
LaunchAgent	~/Library/LaunchAgents/dev.lunarlabs.flavor.flavord.plist, or sh.brew.flavor.plist with Homebrew

If XDG_DATA_HOME, XDG_CONFIG_HOME or XDG_RUNTIME_DIR are set, Flavor uses them instead, as on Linux.

Warning

Deleting ~/Library/Application Support/flavor deletes this Mac's identity on every network. The machines stay registered on their control servers until an administrator removes them.

Running the daemon

The LaunchAgent starts flavord at login. If flavord exits with an error, launchd restarts it; after a clean stop it stays stopped.

launchctl print gui/$(id -u)/dev.lunarlabs.flavor.flavord | grep -E 'state|pid'
launchctl kickstart -k gui/$(id -u)/dev.lunarlabs.flavor.flavord
launchctl bootout gui/$(id -u)/dev.lunarlabs.flavor.flavord
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.lunarlabs.flavor.flavord.plist
tail -f ~/Library/Logs/flavord.log

These are, in order: status, restart, stop, start again, and follow the log.

Don't also start flavord by hand while the LaunchAgent is loaded. The second copy exits because one is already running, and launchd keeps retrying it.

Upgrade

Download and extract the new tarball as above. Then stop the daemon, replace the files and start it again:

launchctl bootout gui/$(id -u)/dev.lunarlabs.flavor.flavord
cp bin/flavord bin/flavorctl ~/.local/bin/
rm -rf ~/Applications/Flavor.app && cp -R Flavor.app ~/Applications/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.lunarlabs.flavor.flavord.plist

Your networks and device identities are kept.

Uninstall

launchctl bootout gui/$(id -u)/dev.lunarlabs.flavor.flavord
rm ~/Library/LaunchAgents/dev.lunarlabs.flavor.flavord.plist
rm ~/.local/bin/flavord ~/.local/bin/flavorctl
rm -rf ~/Applications/Flavor.app

This keeps your data. To delete it as well, remove ~/Library/Application Support/flavor and ~/Library/Logs/flavord.log. Read the warning in Where Flavor keeps its files first.

What works differently from Linux

• System-wide names (flavor-netd, *.flavor.internal in every app) are Linux-only. Port forwarding, the SOCKS5 proxy, the Connection Inspector and everything else work the same.
• Secrets: flavorctl diag shows the macOS Keychain as the secret store (backend keychain).
• The menu bar icon replaces the Linux tray icon. With close-to-tray, clicking Flavor in the Dock shows the window again.

Tested environments

Environment	What was tested	Version
GitHub Actions macos-15 (Apple Silicon) and macos-15-intel	Go and Rust test suites	every commit
2018 Intel MacBook, macOS 15.8.1	daemon and CLI against a real Headscale server, port forwarding, SOCKS5, the LaunchAgent, and the release Flavor.app	release dry run at commit 0d100ec, before v0.1.0-beta.4
2018 Intel MacBook, macOS 15.8.1, Homebrew 7.0.9	tame-gg/tap: formula install and brew test, brew services start and restart, the cask, first launch through Open Anyway, existing networks carried over from the tarball install	v0.1.0-beta.4

Apple Silicon has not been tested by hand yet. Reports are welcome in issues.