OpenMouse: a browser control panel for gaming mice, without per-brand drivers

What OpenMouse replaces, and for whom

Gaming mouse vendors ship a configuration utility per brand. Install three mice and you install three utilities, each with its own updater and background service. OpenMouse takes the opposite position: the control panel is a web page, and the device conversation happens through WebHID, the browser API for HID devices. The README frames the goal plainly: connect a mouse, view its information, and change supported settings such as DPI and polling rate without installing a different app for every brand.

The audience is narrow and worth stating. You need a mouse whose product IDs are already covered by a driver in the companion protocol library. You need a browser that implements WebHID, which in practice means a Chromium-based one. And you need to accept that the settings surface is whatever the driver exposes, not the full feature set of the vendor utility you are leaving behind. If you want per-application profiles or macro recording, this is not the tool.

How the browser talks to the mouse

The architecture is split across repositories, and that split is the most important thing to understand. The control panel itself is thin. According to the README, packet codecs and WebHID drivers live in the standalone @openmouse/protocol library. Codec entry points are transport-independent, meaning they turn bytes into structured values and back without knowing how those bytes travel. The drivers entry points own discovery filters, device clients, retries, and conversion of low-level status into something the application can display.

Inside the panel, the README describes an organization by responsibility: control.ts coordinates the application, while the template, events, DOM helpers, persisted preferences, battery history, device selection, and rendering live in focused modules under src/. The dependency list confirms the shape of the runtime: preact for rendering, lucide-react for icons, and @openmouse/protocol at version 0.2.0 for everything device-facing. OpenMouse consumes the same public exports that external consumers use, so the panel is effectively a reference client for the library rather than a privileged one.

That has a consequence for anyone adding hardware. The README states that OpenMouse should only need changes when a driver introduces a genuinely new UI capability; the control UI otherwise discovers supported clients through the library registry automatically. Vendor work belongs in mouse-protocol, not here.

Installing OpenMouse locally and opening a device

The repository is a private package ("private": true in package.json) with no published npm artifact, so the documented path is a local checkout. Clone the repository, then install dependencies and start the Vite dev server:

npm install
npm run dev

Vite prints a local URL; open it in a Chromium-based browser. The README says this branch is deployed as the public development control panel, so there is also a hosted instance at openmouse.app if you only want to try the interface.

Before pushing changes, the README asks for the full local check, which package.json defines as a type-checked build followed by the test suite:

npm run check

If the build step is what you care about in isolation, npm run build runs tsc --noEmit and then vite build, and npm test runs node --test over src/**/*.test.ts.

On Linux, a device can appear in Chromium's picker and still fail. The README documents the symptom as OpenMouse reporting `Failed to open the device`, and the cause as permissions on the /dev/hidraw* nodes, which Linux does not grant to user sessions by default. Start by identifying the connected device IDs:

lsusb

The README gives a worked example for VXE R1 SE+ hardware, which ships with more than one receiver implementation. If the mouse and the 1K receiver enumerate as 3554:f58f and 3554:f58e, the suggested rules are:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3554", ATTRS{idProduct}=="f58f", TAG+="uaccess"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3554", ATTRS{idProduct}=="f58e", TAG+="uaccess"

Save that as /etc/udev/rules.d/70-openmouse-vxe.rules, reload the rules, then unplug and reconnect both devices:

sudo udevadm control --reload-rules

One detail in the README is easy to miss and will cost you an evening: Chromium opens the HID device before OpenMouse selects its vendor configuration collection, so granting access to only the 0xff02:0x0002 collection's node is not enough. Grant access to every hidraw node for each product ID.

The Linux permission wall is the real onboarding cost

The udev section is not an appendix, it is the failure mode most Linux users will hit first. Two things make it awkward. First, the rules are per product ID, so the example only covers VXE R1 SE+ receivers; any other mouse needs its own vendor and product IDs pulled from lsusb and its own rule file. Second, the README's note about Chromium opening the device before collection selection means a narrowly scoped rule that looks correct on paper can still fail. You end up granting uaccess on all hidraw nodes for the device, which is broader than a reader might expect from a rule file named after one mouse.

There is no documented workaround for this beyond the rules. The README does not describe a fallback transport, a native helper, or a packaged udev rule set. The repository does list an OpenMouse-Bridge among the sibling projects, and the Settings page is documented as comparing the connected bridge against its latest stable GitHub release, but the README does not explain what the bridge does for device access. If you are on Linux and not comfortable editing files under /etc/udev/rules.d, plan for that step before you start.

Configuration, bridge updates, and what the app does not do

The build reads three environment variables, listed in .env.example: VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, and VITE_TURNSTILE_SITE_KEY. Their presence implies the hosted deployment has accounts and bot protection, but the README does not document what the Supabase project stores or whether a self-hosted instance needs all three. Treat that as an open question rather than a documented setup path.

Bridge updates are deliberately manual. The README states that the Settings page compares the connected OpenMouse Bridge against its latest stable GitHub release and retrieves only the version, changelog, and download link. It never downloads or installs an update in the background, and users can also run the check manually. That is a defensible choice for a tool that holds a device handle, though it means update hygiene is the user's problem.

What the app does not do is equally clear. There are no recent releases retrieved for this repository, so there is no changelog to consult for the control panel itself. The README does not document rollback, a device simulator, or a way to import settings from a vendor utility. The package.json test script targets src/**/*.test.ts, and the README places hardware validation checklists in the protocol repository's docs/ directory, which tells you where the testing burden actually sits.

How it compares with vendor utilities and with libratbag

The obvious alternative on Linux is libratbag and its Piper front end, which configure mice through a system daemon over D-Bus. The difference in approach is structural rather than cosmetic. libratbag needs a daemon installed with root privileges and a udev-integrated device database; OpenMouse needs no daemon at all, because the browser process opens the HID device directly and the codecs run in JavaScript. That makes OpenMouse easier to try and harder to make universal: libratbag's device support lives in one C codebase with a long tail of contributed devices, while OpenMouse's support is split between a TypeScript protocol library and per-vendor driver folders, and a device that is not in that registry simply will not appear.

The other alternative is doing nothing and keeping the vendor utility. That is a reasonable answer if your mouse is already configured and you rarely change DPI. OpenMouse earns its place when you switch between several supported mice, or when you want to change polling rate on a machine where you do not want to install a vendor service.

Licence and the cost of staying current

OpenMouse is licensed AGPL-3.0; package.json records the SPDX identifier as AGPL-3.0-or-later, and the README states that contributions are accepted under the same licence. For someone running the panel locally or using the hosted development instance, that changes little. For anyone who wants to fork the panel and run a modified version as a network service, the AGPL's source-availability condition applies to the modified version. This is a description of the licence text, not legal advice; if you plan to redistribute, read the LICENSE file in the repository and take your own counsel.

Maintenance cost is mostly external. The panel pins @openmouse/protocol at 0.2.0, so protocol fixes and new device support arrive by bumping that dependency rather than by patching the UI. The last push to this repository was on 2026-09-17. There are no retrieved releases, so there is no versioned upgrade path to follow for the control panel itself; you track the main branch. If you self-host, that means your upgrade procedure is a git pull, npm install, and npm run check.

Editorial conclusion

OpenMouse is for people who already own a supported mouse and want DPI or polling rate changes without installing another vendor utility, and for developers willing to work inside the mouse-protocol repository when a device is not covered. It is not for you if your mouse is not in the driver registry, if you are on a browser without WebHID, or if you need macro and profile features the repository does not document. Before adopting it, check whether your exact product ID appears in mouse-protocol/src/drivers, confirm your browser exposes navigator.hid, and on Linux verify the /dev/hidraw* permissions for your device rather than assuming the picker alone is enough.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. OpenMouse-Project/openmouse on GitHub
4. Project website
5. README