HeartBeatAgents

Installer Won't Run or Fails Verification

View as Markdown

Docker missing, permission errors, AppImage launch failures, port conflicts, and signature verification problems, with the fix for each.

"Docker is required but not installed"

Install Docker Engine (Linux) or Docker Desktop (macOS/Windows) from docker.com, then verify with docker info and docker compose version.

"Permission denied" running Docker on Linux

Your user isn't in the docker group yet: sudo usermod -aG docker $USER, then log out and back in and confirm with groups | grep docker.

AppImage won't launch on Ubuntu 22.04+

Install the FUSE 2 compatibility library: sudo apt install libfuse2t64 on Ubuntu 24.04+, or sudo apt install libfuse2 on Ubuntu 22.04. If you'd rather not install it, run the AppImage with --appimage-extract-and-run instead.

Port conflict (9500, 9100, or similar already in use)

install.sh scans for a free port automatically, starting from the preferred one and incrementing. Check ~/.heartbeatagents/.env to see which ports it actually allocated.

GPG signature verification fails

  1. Confirm you imported the right public key: gpg --list-keys --fingerprint ops@mosaicsingularity.com. Expected fingerprint: 3041 1399 8510 1531 C54B 0498 1009 78CA B0A0 5886.
  2. If the fingerprint doesn't match, don't trust the package. Someone may have tampered with the key or the file.
  3. Report suspected tampering to ops@mosaicsingularity.com.

macOS says the app "is damaged" or "cannot be opened"

This shouldn't happen since the app is Apple-notarized. If you see it:

  1. Confirm you downloaded from the official release page, not a mirror.
  2. Check the notarization staple: xcrun stapler validate HeartBeatAgents.app.
  3. If the staple is valid but macOS still refuses, the download itself was probably corrupted. Re-download and verify its SHA256 checksum.

Windows SmartScreen warning

The installer is EV-signed, so SmartScreen should accept it without a warning. If you see one, verify the signature with Get-AuthenticodeSignature HeartBeatAgents-Setup-<version>.exe in PowerShell: Status should read Valid and the signer should include Mosaic Singularity Inc. If it doesn't, don't run the installer; report it to ops@mosaicsingularity.com.