Installation and Setup

Installation & Setup

Requirements

• Linux with BlueZ (bluetoothd running). Caeruleus does not build or run on macOS or Windows.
• A standard BLE adapter (built-in or USB). The default adapter is hci0; pass -i hciN for another.
• Root for a handful of raw-socket/system commands (see below).

Install

With the Go toolchain:

go install github.com/praetorian-inc/caeruleus/cmd/caeruleus@latest

Prebuilt release binary (x86_64 and arm64): download the archive for your architecture from the Releases page, extract, and put caeruleus on your $PATH:

sudo install -m755 caeruleus /usr/local/bin/

From source:

git clone https://github.com/praetorian-inc/caeruleus
cd caeruleus
make build        # -> ./caeruleus
make test         # unit tests + shell tests

First run

Confirm the adapter and BlueZ are healthy before anything else:

caeruleus doctor      # OK/WARN/FAIL checklist; exit 2 on FAIL, with a fix per finding
caeruleus scan        # discover nearby devices

If a connect later fails, doctor usually prints the exact fix (adapter power cycle, forget, or an MTU adjustment). See Hardware, Adapters & Troubleshooting.

Commands that need root

Most commands run unprivileged over BlueZ D-Bus. These use raw HCI/L2CAP sockets or system config and need sudo:

conn-params, monitor, fuzz write --raw, cccd --raw, raw-write, mtu --set/--reset, bdaddr --set.

For unattended or agent use, a scoped sudoers drop-in avoids password prompts:

echo "$USER ALL=(root) NOPASSWD: $(command -v caeruleus)" | sudo tee /etc/sudoers.d/caeruleus
sudo chmod 440 /etc/sudoers.d/caeruleus

Next

• Command Reference — every command and flag
• Recipes — copy-paste workflows
• Coming from Another Tool — if you already use another BLE tool