Skip to content

macos.md

Latest commit

 

History

History
198 lines (124 loc) · 4.21 KB

macos.md

File metadata and controls

198 lines (124 loc) · 4.21 KB
Raw

macOS

Install, update, run as a LaunchAgent, and uninstall on macOS (Intel or Apple Silicon).

Install

./install.sh

That is the whole install. Run it from a clone, or pipe it from curl:

sh

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

The canonical installation paths explain the fast and guided routes, source fallback, app selection, PATH handoff, and the next Quickstart step.

Homebrew

sh

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:

sh

export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw"

Add that to your shell profile if you want it permanent.

System dependencies

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-attached board. See Hardware
iMessage channel Requires macOS 11+. See Channels → Other chat platforms

Running as a service

sh

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/):

sh

tail -f ~/.zeroclaw/logs/daemon.stdout.log

For Homebrew installs, prefer:

sh

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.

Update

Re-run the installer, it detects the existing install and upgrades in place:

sh

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh -s -- --skip-quickstart
zeroclaw service restart

Or from a clone:

sh

cd /path/to/zeroclaw
git pull
./install.sh --skip-quickstart
zeroclaw service restart

If installed via Homebrew instead:

sh

brew update && brew upgrade zeroclaw
brew services restart zeroclaw

Uninstall

sh

# 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):

sh

# Homebrew workspace
rm -rf "$HOMEBREW_PREFIX/var/zeroclaw"

# Default workspace (includes logs at ~/.zeroclaw/logs)
rm -rf ~/.zeroclaw ~/.config/zeroclaw

Gotchas

  • Homebrew config path mismatch. The 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.
  • First launch of the browser tool downloads Chromium (~150 MB) via Playwright.
  • Apple Silicon and Intel: the bootstrap script detects the architecture and uses a matching prebuilt release artifact when one is available. If the release has no matching artifact, it falls back to a source build. Homebrew selects the appropriate package for the host.

Next