macOS Installation¶

Disclaimer

AIS-catcher is intended for hobbyist and research projects only. It is NOT approved for use in navigation or safety-of-life applications. Read the full disclaimer.

Installation¶

This guide provides instructions for installing AIS-catcher on macOS systems using Homebrew. AIS-catcher is built from source on macOS to ensure optimal performance for your specific hardware. Once installed, there are two ways to run your station:

Managed mode (recommended) — configure and control your station from the browser.
Manual mode — configure via command-line options.

Prerequisites¶

Install Homebrew¶

If you don't already have Homebrew installed, you can install it by opening a terminal and running:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions to complete the installation. After installation, you may need to add Homebrew to your PATH as instructed.

Installation Steps¶

1. Install Build Dependencies¶

First, ensure you have the necessary build tools and dependencies:

brew update
brew upgrade

brew install git make gcc cmake pkg-config sqlite3

2. Install SDR Hardware Libraries¶

Depending on your SDR hardware, install the appropriate drivers. For RTL-SDR dongles (most common):

brew install librtlsdr

For other hardware types, install the corresponding libraries:

Hardware	Homebrew Package
RTL-SDR	`librtlsdr`
Airspy	`airspy`
Airspy HF+	`airspyhf`
HackRF	`hackrf`
ZeroMQ	`zeromq`

For example, to install support for Airspy and HackRF:

brew install airspy hackrf

3. Build and Install AIS-catcher¶

Once the dependencies are in place, clone the repository and build AIS-catcher:

git clone https://github.com/jvde-github/AIS-catcher.git --depth 1
cd AIS-catcher
mkdir build
cd build
cmake ..
make
sudo make install

The build process will automatically detect and include support for any SDR libraries you have installed. You can verify the result and the features included in your build with AIS-catcher -L.

Note

Building from source can take several minutes depending on your Mac's specifications. The executable will be optimized for your specific hardware.

Managed Mode¶

Start AIS-catcher in managed mode

AIS-catcher -E ~/aiscatcher.json 127.0.0.1:8118

Complete the setup wizard
Open the dashboard in your browser at http://localhost:8118. On first use, the setup wizard walks you through configuring your input device and outputs, and starts the receiver:

Setup Wizard

That's it — your station is up and running. See Getting Around the Dashboard to monitor and fine-tune it.

Manual Mode¶

Alternatively, start receiving AIS messages with your RTL-SDR dongle directly from the command line:

AIS-catcher -v 10

Command Line Run

Running as a Background Service¶

Unlike the Linux/Raspberry Pi version, there is no automated background service setup script for macOS. However, you can create a launch agent to run AIS-catcher automatically at startup using launchd.

Creating a Launch Agent¶

First, verify the installation path of AIS-catcher:

which AIS-catcher

This will return either /usr/local/bin/AIS-catcher (Intel Macs) or /opt/homebrew/bin/AIS-catcher (Apple Silicon Macs). Use this path in the next step.

Create a launch agent plist file (note: do not use sudo for this):

nano ~/Library/LaunchAgents/com.aiscatcher.plist

Add the following content, adjusting the path and parameters for your setup:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.aiscatcher</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/AIS-catcher</string>
        <string>-v</string>
        <!-- Add additional parameters as separate strings, for example: -->
        <!-- <string>-u</string> -->
        <!-- <string>5.9.207.224</string> -->
        <!-- <string>2947</string> -->
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/aiscatcher.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/aiscatcher.error.log</string>
</dict>
</plist>

Important Notes: - Replace /usr/local/bin/AIS-catcher with the path from step 1 if different (e.g., /opt/homebrew/bin/AIS-catcher for Apple Silicon) - Replace YOUR_USERNAME with your actual macOS username - Each command-line argument must be in its own <string> tag (e.g., -u, 5.9.207.224, and 2947 as three separate strings) - Logs are stored in your home directory to persist across reboots (unlike /tmp which is cleared on restart)

Load the launch agent:

launchctl load ~/Library/LaunchAgents/com.aiscatcher.plist

To start the service immediately:

launchctl start com.aiscatcher

To stop the service:

launchctl stop com.aiscatcher

To unload the service (if you need to make changes to the plist):

launchctl unload ~/Library/LaunchAgents/com.aiscatcher.plist

Updating AIS-catcher¶

To update to the latest version, navigate to your AIS-catcher directory and rebuild:

cd AIS-catcher
git pull
cd build
cmake ..
make
sudo make install

Troubleshooting¶

Command Not Found¶

If you get a "command not found" error after installation, ensure /usr/local/bin is in your PATH. Add this to your ~/.zshrc or ~/.bash_profile:

export PATH="/usr/local/bin:$PATH"

CMake Not Found¶

If cmake is not found, ensure Homebrew is properly installed and in your PATH. After installing Homebrew, you may need to run the commands shown at the end of the Homebrew installation.

Missing Libraries¶

If the build fails due to missing libraries, make sure you've installed the required SDR libraries with Homebrew as described in step 2.

Alternative: MacPorts¶

While this guide focuses on Homebrew, AIS-catcher can also be built using MacPorts. The following instructions were contributed by the community (credit: GitHub Discussion #500).

Prerequisites¶

First, install Xcode command line tools:

xcode-select --install

Download and install MacPorts from macports.org/install.php, choosing the version specific to your macOS release.

Installation Steps¶

Install base prerequisites via MacPorts:

sudo port install git make gcc cmake sqlite3

Install your SDR device driver. For RTL-SDR dongles:

sudo port install rtl-sdr

For other hardware, install the corresponding MacPorts package.

Download, build, and install AIS-catcher:

cd
git clone https://github.com/jvde-github/AIS-catcher.git --depth 1
cd ~/AIS-catcher
mkdir ~/AIS-catcher/build
cd ~/AIS-catcher/build
cmake ..
make
sudo make install

After installation, verify it works by running:

AIS-catcher -L