import ThemedImage from '@theme/ThemedImage';

Getting Started

Two ways to get DeckBridge (what it is): run a packaged release (easiest) or build from source.

1. Get DeckBridge

Option A — Packaged release (recommended)

caution

Releases are built and tested on macOS. Windows and Linux builds are produced by the same release workflow but are far less exercised — if one misbehaves, build from source (Option B). The Linux binaries need glibc 2.38 or newer (Ubuntu 24.04+, Debian 13+); on an older distro, build from source.

Download the build for your OS from the project releases, unzip, and run. It's self-contained — the txiki.js runtime and native libraries (libhidapi, libdeckbridge_native) are embedded and auto-extract on first run. No Node.js, no extra installs.

./deckbridge        # macOS / Linux
deckbridge.exe      # Windows

The macOS .dmg and Windows installer also bundle a small system-tray companion.

Option B — Build from source

Needs mise, a Rust toolchain, and libhidapi:

macOS: brew install hidapi
Debian/Ubuntu: sudo apt install libhidapi-dev

cd deckbridge
mise run start      # build everything + run
# or
mise run compile    # produce a standalone ./deckbridge binary

mise fetches a prebuilt slim txiki.js runtime automatically — no C/C++ toolchain needed on macOS arm64, Windows, or Linux (x86_64/arm64). Only macOS x86_64 has no prebuilt asset and builds from source (needs git, cmake, npm, libffi). Set TJS_FROM_SOURCE=1 to force the source build anywhere — e.g. on a distro older than glibc 2.38.

2. Plug in your deck

Connect a supported device. DeckBridge probes on start and retries every 2 s until one opens. On macOS, grant Input Monitoring if prompted — HID reads need it (see Permissions).

3. Run it

Start DeckBridge. It then:

opens the USB device,
advertises an Elgato Network Dock over mDNS (_elg._tcp),
listens on TCP 5343 / 5344 (CORA protocol),
serves a web UI at http://localhost:3000.

In packaged releases (installers and release zips) the tray icon shows status at a glance:

Tray icon	State	Meaning
	gray	no deck
	yellow	deck connected and ready for pairing with Elgato app
	green	deck open and Elgato app connected

4. Pair with the Elgato app

Open the Elgato Stream Deck app (or Companion) on any machine on the same LAN. It discovers DeckBridge like real Elgato hardware.

The web UI walks you through it — it shows the connected deck and the exact address and port to enter in the Elgato app:

A second deck (different model) appears as its own network device on its own port (5345, 5347, …) — pair each separately. The web UI shows a card per deck with the exact address and port; see Multiple decks.

Verify your setup

Open http://localhost:3000 for the live key grid and log feed.
Or use the tray's Check Requirements → the /requirements diagnostics page (what it checks: Requirements).
Switch the web UI to Advanced (top-right) for the live dashboard — key grid, mock devices, brightness, image-fit modes, and a real-time log feed.

Troubleshooting

port in use (5343/5344) — another DeckBridge, a real Network Dock, or the ESP32 bridge holds the CORA port. Stop it; DeckBridge keeps retrying every few seconds.
No device found — check the cable/port; on macOS grant Input Monitoring. DeckBridge retries every 2 s.
libhidapi missing (source build only) — install it as in Build from source.
Permission denied opening the deck (Linux) — add a udev rule; see Permissions.
Restrict network access — set DECKBRIDGE_BIND=127.0.0.1; see Network ports.

1. Get DeckBridge​

Option A — Packaged release (recommended)​

Option B — Build from source​

2. Plug in your deck​

3. Run it​

4. Pair with the Elgato app​

Verify your setup​

Troubleshooting​