Motrix WebExtension: routing browser downloads through a desktop download manager via aria2 RPC

What the extension intercepts and what it leaves to the browser

Clicking a download link in Chrome, Edge, Firefox or Opera normally hands the file to the browser's own download manager. Motrix WebExtension intercepts that handoff and routes the request to Motrix instead, before the browser has a chance to save it locally. From that point, Motrix and its aria2 backend handle the transfer.

People who already run Motrix and want their browser's downloads to land there automatically are the intended audience. Neither the README nor the package.json documents categorisation, per-domain filtering, or any scheduling layer beyond what Motrix itself offers. All-or-nothing interception is what the extension does: every download the browser would have handled goes to Motrix, without exception or rule.

According to the repository description, the extension also works with forks of Motrix, though no specific forks are named. Compatibility with a fork depends on whether that fork exposes the same aria2 RPC interface Motrix uses, and no list of tested forks or versions appears in any repository file.

aria2 RPC is the only channel between the extension and the desktop app

Motrix exposes an RPC interface, and the extension uses it to tell Motrix to start a download. Looking at package.json, the aria2 npm package at version 5.0.0 is a direct runtime dependency, alongside React 17.0.2, MUI 5.0.4 and webextension-polyfill 0.12.0. That aria2 package handles the JSON-RPC communication to the running Motrix process.

A shared secret token is required for every connection. Motrix generates the token; the extension includes it in each RPC call. Mismatching the stored secret in Motrix with what the extension holds causes every request to fail silently. A port option also exists: Motrix lets you change the RPC listen port from its default, and the extension has a matching set port option for when you do.

What the default port number actually is does not appear in the README or in any repository file included here. Determining the correct value requires consulting Motrix's own documentation separately, and if that port is blocked by a firewall or already in use by another process, neither the README nor the extension settings page documents how to diagnose the conflict or what alternative port to try.

Store install or building from source: what each path gives you

Chrome, Opera and Edge users can install from the Chrome Web Store, where the extension carries ID djlkbfdlljbachafjmfomhaciglnmkgj. Firefox users go to Mozilla Add-ons, where the listing name is motrixwebextension. Store installs handle updates automatically.

Building from source requires Node and Yarn. Package.json names [email protected] as the package manager. Install dependencies first:

yarn install

A development build for a specific browser runs with:

yarn run dev chrome
yarn run dev firefox

Production builds use:

yarn run build chrome
yarn run build firefox

Webextension-toolbox at version 7.1.1 drives the build. It defines process.env.NODE_ENV in the extension's scripts, which behaves as that tool sets it rather than as a typical server-side Node.js environment. A playwright.config.js and a tests/ directory are present in the repository; the package.json scripts show tests run per browser. Installing-via-releases.md in the repository root has more detail on loading a built extension into the browser, but its content is not reproduced in the README.

Setting the RPC secret in Motrix before any download routes correctly

Setup follows two numbered steps in the README, and order matters.

First, open Motrix and go to Preferences, then Advanced, then Security, then RPC secret. Generate a random key there and copy it. Changing the RPC listen port is optional; if you do change it in Motrix, the same value must be entered in the extension using the set port option.

Second, open the extension settings in the browser, paste the copied key, and click SET KEY. At that point, setup is complete according to the README.

No confirmation step follows in the documented flow. No status indicator shows whether the extension is currently connected to a running Motrix instance. When a download goes nowhere after setup, the two values to verify are the secret and the port: confirm they match on both sides before looking further.

Motrix must stay open: what happens when it is not

One line in the README covers the main failure mode directly: "You should keep Motrix always running in the background for this extension to work. We cant launch motrix programmatically."

When the extension forwards a download request and Motrix is closed, the RPC call reaches nothing. What happens next is not documented: whether the file is lost, held in a queue, or whether the browser shows an error is an open question the README does not answer. For any download that matters, confirm Motrix is open before starting it.

Startup behaviour is also a factor. On no platform does Motrix launch at login by default, and enabling that behaviour is a preference inside Motrix itself, not something the extension can configure. Anyone who restarts their computer regularly or whose machine wakes from sleep to a fresh session should confirm that Motrix is set to start at login before counting on the extension for downloads that matter.

File type filtering is absent, and the browser is the documented fallback

Once active, the extension sends every download to Motrix without distinction. No per-type or per-domain filtering is described in the README, and the extension's documented settings cover only two values: the RPC secret and the RPC port. Sending large binary files to Motrix while keeping PDFs or small text files in the browser is not a supported configuration.

For users who want Motrix to handle only specific downloads, the only available workaround is disabling the extension in the browser's extension manager before downloads they want to keep locally, then re-enabling it. Nothing in the README describes that workflow as intended. Building a custom version with a domain or file-type blocklist would require modifying the app/ source.

Anyone who does not already depend on Motrix has a simpler path: keep using the browser's native download manager and skip the extension entirely. No configuration is required, no desktop application must stay open, and no RPC connection needs maintenance. Installing the extension makes sense only when Motrix is already a regular part of the workflow.

Package.json version 2.0.1 cannot be ordered against the date-based GitHub tags

Package.json carries version "2.0.1", while the GitHub tags follow a date-based scheme: 26.9.9 corresponds to 2026-09-09, and 26.6.17 to 2026-06-17, with nothing in the repository explaining when or why the naming changed. The last push was on 2026-10-02, and the project is licensed under GPL-3.0.

For tooling that reads package.json to decide whether an update is needed, this creates a silent problem. Comparing "2.0.1" against "26.9.9" produces no meaningful ordering, since the two strings belong to incompatible schemes: one looks like semantic versioning, the other encodes a calendar date formatted as year.month.day with the century stripped. Anyone tracking the extension as a dependency has to consult the GitHub tags directly, not the manifest.

Two maintainers are listed: @gautamkrishnar and @JaroslawPokropinski. Bug reports go to the GitHub issue tracker, which the README links directly.

Editorial conclusion

Motrix WebExtension is worth installing if you already run Motrix and want every browser download to route through it automatically. The two-step setup is straightforward, but the operational dependency is real: Motrix must stay open at all times, or downloads will not complete. The extension is a poor fit if you expect it to categorise files, apply different rules per domain, or launch Motrix for you when it is closed. Before relying on it, test with one download and confirm it appears in Motrix's queue, because the README provides no connection test and gives no indication when the RPC link is down.

Frequently asked questions

Official sources

1. gautamkrishnar/motrix-webextension on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases