docs/book/src/setup/macos.md
Install, update, run as a LaunchAgent, and uninstall on macOS (Intel or Apple Silicon).
./install.sh
That is the whole install. Run it from a clone, or pipe it from curl:
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
The installer picks a prebuilt binary or builds from source (interactive by default), installs to ~/.cargo/bin/zeroclaw, and offers to run zeroclaw quickstart for first-time setup. Pass --help for the full flag reference, or --skip-quickstart to install only.
brew install zeroclaw
Gets you brew services integration. Binary lives at $HOMEBREW_PREFIX/bin/zeroclaw.
Workspace location gotcha: with Homebrew, the service user and the CLI user may be different, so the workspace lives at $HOMEBREW_PREFIX/var/zeroclaw/ rather than ~/.zeroclaw/. Point CLI invocations at the same workspace:
export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw"
Add that to your shell profile if you want it permanent.
Most features work with a stock macOS install. Optional extras:
| Feature | Install |
|---|---|
| Docs translation | brew install gettext |
| Browser tool | Playwright pulls Chromium automatically on first use |
| Hardware | No native GPIO on macOS; use a USB peripheral like Aardvark. See Hardware → Aardvark |
| iMessage channel | Requires macOS 11+. See Channels → Other chat platforms |
zeroclaw service install # writes ~/Library/LaunchAgents/com.zeroclaw.daemon.plist
zeroclaw service start
zeroclaw service status
Logs go to ~/.zeroclaw/logs/ (Homebrew installs: $HOMEBREW_PREFIX/var/zeroclaw/logs/):
tail -f ~/.zeroclaw/logs/daemon.stdout.log
For Homebrew installs, prefer:
<div class="os-tabs-src">brew services start zeroclaw
brew services info zeroclaw
Both methods produce the same end state, a loaded LaunchAgent that starts on login. Pick one and stick with it.
Full details: Service management.
Re-run the installer, it detects the existing install and upgrades in place:
<div class="os-tabs-src">curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash -s -- --skip-quickstart
zeroclaw service restart
Or from a clone:
<div class="os-tabs-src">cd /path/to/zeroclaw
git pull
./install.sh --skip-quickstart
zeroclaw service restart
If installed via Homebrew instead:
<div class="os-tabs-src">brew update && brew upgrade zeroclaw
brew services restart zeroclaw
# stop and unregister the service
zeroclaw service stop
zeroclaw service uninstall
# Homebrew
brew uninstall zeroclaw
# bootstrap / cargo
rm ~/.cargo/bin/zeroclaw
Remove config and workspace (optional: this deletes conversation history):
<div class="os-tabs-src"># Homebrew workspace
rm -rf "$HOMEBREW_PREFIX/var/zeroclaw"
# Default workspace (includes logs at ~/.zeroclaw/logs)
rm -rf ~/.zeroclaw ~/.config/zeroclaw
brew services daemon reads config from $HOMEBREW_PREFIX/var/zeroclaw/, not ~/.zeroclaw/. If your service is reading stale config, check which one the daemon sees and set ZEROCLAW_WORKSPACE accordingly.