Platform setup

New here? Windows users should follow GETTING-STARTED.md, which explains every click. This page covers the other systems and the more technical options.

Some steps below use a terminal: on a Mac open Terminal (Applications → Utilities); on Linux press Ctrl+Alt+T or search for Terminal. Type each command and press Enter. Commands starting with sudo ask for your computer password (nothing shows as you type; that is normal).

The bridge must run on the machine the deck is plugged into. Companion can be anywhere on the network: set COMPANION_HOST (and COMPANION_PORT) to reach its Satellite API.

Verification status: an AKP05E has been run on a real Windows PC and on a real Unraid 7.3.2 server. On Unraid the published Docker image ran without Privileged, with only the pad's /dev/hidrawN node mapped, registered with a real Companion container, drew every image, and delivered every key, touch zone, swipe and dial turn that was tried. Linux (Debian, Node 22) passes install, lint and the full test suite; the generated systemd unit passes systemd-analyze verify; the launchd plist is well-formed. macOS, and Linux outside Docker, have not been tried with a real deck.

Ready-to-run downloads

The Releases page offers bundles for Windows (.zip), macOS Apple silicon and Intel (.tar.gz) and Linux (.tar.gz). Each contains the bridge, its dependencies, the docs and its own copy of Node.js, so you do not install Node. Unpack it somewhere permanent and use the launcher for your system:

You build the same bundle yourself with npm run package (on the OS and CPU you want to ship for). Pushing a v* tag makes GitHub build all bundles and attach them to the release (.github/workflows/release.yml).

Windows

1. Install Node.js 20+. Double-click setup.cmd, or run npm install and copy .env.example to .env.
2. npm start. The tray icon shows status and offers Open log, Open folder, Reconnect, Start at login and Quit.
3. Start at login: the tray item, or npm run install-startup (npm run uninstall-startup to remove). This puts a launcher in your Startup folder that runs launch-bridge.vbs → src/supervisor.js in a hidden window; the supervisor restarts the bridge if it crashes and stops when you choose Quit.
4. No Node on the target PC? npm run package builds dist/ajazz-bridge-portable.zip with Node and the native modules included (build it on the OS you ship to).

macOS

If you used the ready-to-run download: macOS puts downloaded files in "quarantine", so the first launch can be blocked with "cannot be opened because the developer cannot be verified". Fix it once by opening Terminal, typing xattr -dr com.apple.quarantine (with a trailing space), dragging the unpacked folder onto the Terminal window, and pressing Enter. Then double-click Start Ajazz Bridge.command (if macOS still objects, right-click it and choose Open). The bundles are not code-signed.

Step 1 uses Homebrew. If you don't have it, install Node.js from nodejs.org instead and skip that command.

1. brew install node, then npm install and copy .env.example to .env.
2. npm start. A menu-bar icon appears (BRIDGE_NO_TRAY=1 hides it). The first time the deck is read, macOS may ask to allow Input Monitoring for your terminal or Node.
3. Start at login: npm run install-startup writes ~/Library/LaunchAgents/com.ajazz.bridge.plist and loads it; npm run uninstall-startup removes it. Output goes to launchd.out.log / launchd.err.log in the bridge folder.

Linux (desktop or server)

On Linux a normal user is not allowed to talk to USB devices until you add a permission rule (step 2). If you skip it the bridge reports a permission denied error.

1. Install Node.js 20+. If no prebuilt USB module matches your system: sudo apt install libudev-dev libusb-1.0-0-dev build-essential. Then npm install.
2. Allow your user to open the deck:

   node scripts/udev-rules.js | sudo tee /etc/udev/rules.d/99-ajazz-bridge.rules
   sudo udevadm control --reload && sudo udevadm trigger
   

   Then unplug and replug the deck. The rules grant the logged-in desktop user (uaccess) and the plugdev group; on a headless server add the service user to plugdev. A copy is committed at deploy/linux/99-ajazz-bridge.rules.
3. npm start. The tray icon only shows when a display server exists (it is off by default over SSH, on servers and in containers; BRIDGE_NO_TRAY=0 forces it).
4. Start at login/boot: npm run install-startup creates a systemd user service. Then systemctl --user start ajazz-bridge, and loginctl enable-linger $USER so it runs without an open session. Logs: journalctl --user -u ajazz-bridge and bridge.log.

Docker

Docker packages the bridge so you don't install Node yourself. It suits servers and home labs; on a desktop PC the normal install above is easier.

The image is headless and configured with environment variables; logs and the lock go to /config.

docker run -d --name ajazz-bridge --restart unless-stopped --network host \
  -e COMPANION_HOST=127.0.0.1 -e COMPANION_PORT=16622 -v $PWD/config:/config \
  --device=/dev/hidraw0 ghcr.io/dvortsis/ajazz-companion-bridge:latest

The image is published for amd64 and arm64 and needs no login to pull. To build it yourself instead, run docker build -t ajazz-companion-bridge . in this folder and use that name in place of the ghcr.io/... one.

or docker compose up -d with the included docker-compose.yml. The deck appears as /dev/hidrawN (ls -l /dev/hidraw*); pass that device with --device, or use --privileged if the number changes between boots. Install the udev rules on the Docker host too. docker logs ajazz-bridge should show [HID] Secured … and ADD-DEVICE OK. Tagging a release (v*) on GitHub publishes ghcr.io/<owner>/ajazz-companion-bridge for amd64 and arm64 with .github/workflows/docker.yml.

Unraid

The pad must be plugged into the Unraid server for this route. If it is plugged into your PC, run the bridge on the PC instead (step 6).

1. Install the template. Once the app is listed in Community Applications, open Apps and search for "ajazz". Until then (or if you prefer), copy templates/ajazz-companion-bridge.xml from this repository to /boot/config/plugins/dockerMan/templates-user/ on the server, then choose Docker → Add Container → ajazz-companion-bridge.

2. Nothing to build: the template pulls the published image ghcr.io/dvortsis/ajazz-companion-bridge:latest. (To use a copy you built yourself, run docker build -t ajazz-companion-bridge /path/to/ajazz-bridge and set Repository to that name.)

3. Set Companion host to the IP of the machine that runs Companion (the Unraid IP if Companion is another container on this server).

4. Set USB HID device to the pad's node. The pad shows up as two /dev/hidrawN entries (the pad itself and a keyboard-style interface); you need the first one, whose HID_PHYS ends in /input0. In the Unraid terminal, with the pad plugged in, run:

   for d in /sys/class/hidraw/hidraw*; do grep -q 00000300:00003004 $d/device/uevent && echo "$(basename $d) $(grep HID_PHYS $d/device/uevent)"; done
   

   Example output: hidraw7 HID_PHYS=usb-0000:00:14.0-2.4/input0 and hidraw8 … /input1: use /dev/hidraw7. The number can change after a reboot, a replug or other USB devices, so check it again if the pad stops responding.

5. Start the container and open its log. You should see [HID] Secured … and ADD-DEVICE OK. The template runs without Privileged, which has been verified on Unraid 7.3.2. If it says No supported devices found, check you picked the /input0 node from step 4; as a last resort switch Privileged on (Advanced View).

6. If the deck is plugged into another PC rather than Unraid, run the bridge on that PC and point it at Companion on Unraid.