macOS Installation

Download the macOS ARM64 standalone archive for Apple Silicon or macOS x64 for an Intel Mac from Releases. Node.js is included. For a checkout, use Source installation.

Verify and run

Download the matching .sha256 file. From the download directory, use the exact filename from the release, for example:

shasum -a 256 -c GearBeacon-v1.2.0-macos-arm64.tar.gz.sha256
tar -xzf GearBeacon-v1.2.0-macos-arm64.tar.gz

Enter the extracted package directory and run:

./gearbeacon

Open http://localhost:8787. Portable data lives in ~/Library/Application Support/GearBeacon. Keep the process running to monitor. Keep the executable, web, and manifest together.

Packages are currently unsigned and not notarized. A checksum verifies the downloaded bytes against the release; it does not remove macOS security prompts. Review the source and release provenance before making any platform-specific trust decision.

Install a LaunchDaemon

Close any portable process, then run from the extracted standalone package:

sudo ./install-macos-service.sh

The installer creates a dedicated _gearbeacon identity, root-owned application files, and a service-owned data directory. Initial access defaults to authenticated private mode, binding 0.0.0.0.

Component	Location
Application	/usr/local/lib/gearbeacon
Data	/Library/Application Support/GearBeacon
Log	/Library/Application Support/GearBeacon/gearbeacon.log
LaunchDaemon	/Library/LaunchDaemons/com.gearbeacon.server.plist
Label	com.gearbeacon.server

The service data path differs from the portable path. Transfer an existing installation using Backups and recovery, keeping its database and encryption key together.

Check, stop, or start

sudo launchctl print system/com.gearbeacon.server
sudo tail -n 50 '/Library/Application Support/GearBeacon/gearbeacon.log'

To stop the loaded daemon:

sudo launchctl bootout system /Library/LaunchDaemons/com.gearbeacon.server.plist

To start it again after it has been unloaded:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.gearbeacon.server.plist

Read the setup token locally from the log and complete first run. The daemon runs independently of your desktop session. Mounted backup storage must be accessible to _gearbeacon when the daemon runs; verify it with the backup and restore-test controls.

Update or uninstall

Use the backup-confirmed native helper described in Updates and rollback. Run sudo ./uninstall-macos-service.sh from the package to uninstall; it preserves data unless explicitly given --remove-data.

Implementation: macOS installer, uninstaller, native updater.