Linux Installation

Download the Linux x64 or Linux ARM64 standalone archive matching your host from Releases. It includes Node.js. For NAS systems without a compatible systemd environment, use Docker.

Verify and run

Download the matching checksum file and run from the download directory, substituting the exact release asset name:

sha256sum -c GearBeacon-v1.2.0-linux-x64.tar.gz.sha256
tar -xzf GearBeacon-v1.2.0-linux-x64.tar.gz

Enter the extracted package directory and run ./gearbeacon, then open http://localhost:8787. Keep the package's web directory and manifest beside the executable. Portable data lives in ${XDG_DATA_HOME:-~/.local/share}/GearBeacon.

Archives include checksum/SBOM/provenance metadata, but the executable is not natively code-signed. Linux distribution and runtime-library compatibility still matters; use a supported host or the container image if the executable reports missing system libraries.

Install a systemd service

Close any portable instance. From the extracted standalone package:

sudo ./install-linux-service.sh
sudo systemctl status gearbeacon
sudo journalctl -u gearbeacon -n 50 --no-pager

The installer uses /opt/gearbeacon for root-owned application files, /var/lib/gearbeacon for service-owned data, and /etc/systemd/system/gearbeacon.service for the unit. The process runs as the dedicated gearbeacon user/group with authenticated private mode and an initial 0.0.0.0 bind.

Read the one-time setup token from the journal locally, finish first run, and restrict access to the intended LAN/VPN or same-host HTTPS proxy.

The unit enables filesystem and process restrictions, including ProtectSystem=strict, ProtectHome=true, NoNewPrivileges=true, private temporary/device namespaces, and an explicit writable data path. Keep these protections when customizing the unit.

Manage the process

sudo systemctl stop gearbeacon
sudo systemctl start gearbeacon
sudo systemctl restart gearbeacon
sudo journalctl -u gearbeacon -f

Use the commands individually as needed. Do not run a second portable instance against the service's data directory. Portable and service installations have different default data paths; see migration and restore.

Allow a secondary backup mount

The default unit permits writes only under /var/lib/gearbeacon. A separate disk/share needs both filesystem permission for gearbeacon and a systemd writable-path exception. For an example mount at /mnt/gearbeacon-backups, open a drop-in:

sudo systemctl edit gearbeacon

Add:

[Service]
ReadWritePaths=/mnt/gearbeacon-backups

Replace the example with an existing, mounted destination owned or appropriately writable by the service identity. Ensure the mount is available before the service starts. Reload the unit, restart, then set the path in Settings > Data:

sudo systemctl daemon-reload
sudo systemctl restart gearbeacon

Create a backup and test the secondary restore. Do not disable the whole sandbox to permit one backup directory. GearBeacon rejects symbolic-link destinations and reports a failed secondary copy separately from a successful primary backup.

Update or uninstall

Follow Updates and rollback for the backup-confirmed native helper. sudo ./uninstall-linux-service.sh removes the service/application and preserves data unless explicitly given --remove-data.

Implementation: Linux installer, uninstaller, native updater.