Motrix v2: A Download Manager Rebuilt Around an Open Protocol and Plugin Sandbox

What Motrix v2 Actually Changes

Motrix v1 was a desktop download manager. Motrix v2, branded as Motrix Turbo, is a rebuild from the ground up with Electron, React, and TypeScript. The key architectural move is that the download core is independent of the UI. That means the same engine runs as a desktop app on macOS, Windows, and Linux, or as a headless server on Node.js or in Docker with a web UI. The README positions this as a way to serve NAS devices and home servers. For an engineer, the practical effect is that you can drive downloads without ever opening a window. The protocol that makes this possible is MDXP, or Motrix Download eXchange Protocol, built on JSON-RPC 2.0. The protocol is open and defined in a separate npm package, @motrix/mdxp, which includes Zod types and helpers for bidirectional connections. That is a concrete difference from v1, which had no such separation.

The MDXP Protocol and How Clients Talk to the Core

MDXP is not just a name in a README. The repository lists @motrix/mdxp as a shared protocol library that defines JSON-RPC 2.0 wire schemas and Zod types. The CLI, browser extensions, and plugins all communicate with the core over this protocol. The CLI quick start shows the pattern: you install @motrix/cli globally, then run commands like motrix add https://example.com/file.iso --save-dir ~/Downloads, motrix list, and motrix watch --stats, which streams live progress as NDJSON. The CLI also supports pairing with remote instances via motrix pair --name my-nas. That pairing is described as secure device-code pairing for the headless server. The browser extensions, for Chrome and Firefox, intercept downloads and hand them off to Motrix over native messaging, with a pairing step. So the data flow is: a client (CLI, browser, or plugin) sends a JSON-RPC request over MDXP to the core, which performs the actual HTTP, FTP, or BitTorrent transfer. The UI is just another client. This is a clean separation, and it means you could write your own client against the protocol, as long as you respect the Zod schemas.

Plugin Sandboxing with QuickJS: What You Can and Cannot Do

Plugins are a major part of v2. They are bundled as a single ES2020 module and run inside a QuickJS sandbox. The README is explicit that plugins do not have Node.js APIs or direct file and network access. Instead, they hook into lifecycle events: beforeCreate, beforeFinalize, afterComplete, and onError. They can contribute callable commands and settings, and access the runtime through a virtual module called motrix:plugin-api. Permissions are declared in motrix-plugin.json, with activation events, required capabilities, and URL-scoped host permissions. Motrix shows those requests to the user before granting access. This is a genuine security boundary, not a marketing claim. The trade-off is that you cannot write a plugin that does arbitrary system calls or reads local files. If you need that, you are out of luck. The official built-in plugins include Filename Template, Page Scraper, and URL Resolver, all signed as .moext packages. The Plugin SDK provides a scaffolder: pnpm create motrix-plugin my-plugin, then pnpm dev to watch-build and launch Motrix with the plugin, and pnpm exec motrix-plugin validate to check the manifest. The sandbox is a real constraint, but it is also what makes the marketplace feasible without turning the app into a security hole.

Installation and First Run: Desktop, CLI, and Docker

The README gives three distinct installation paths. For the desktop app, you download a package from motrix.app and choose the one for your OS; the note says most Mac users should pick the Apple Silicon build, though the exact package names are truncated. For the CLI, you need Node.js 22 or later and run npm install -g @motrix/cli. The CLI automatically discovers a local desktop app and can pair with remote instances. For a headless server, you use Docker; the README mentions a Docker-ready headless server with secure device-code pairing, but does not give a docker run command in the visible portion. The web UI is included for NAS devices. The README also mentions handlers for motrix:// and magnet: links, plus .torrent file associations, so the desktop app integrates with the OS. The beta release notes are available at docs/release-notes/2.0.0-beta.28.md, and the README strongly advises reading them before installing. There is no mention of a package manager like apt or Homebrew in the visible text, so you are expected to grab the binary from GitHub Releases.

The Beta Risk: Data Migration Is Not Validated

The most important caveat is in the beta testing section. The README says, verbatim: 'Back up your existing Motrix data and downloads before testing. Migration from Motrix v1 data has not yet been validated, so do not use your only copy of v1 data with this beta.' That is a direct warning that upgrading from v1 could lose your data. The recommended practice is to test v2 in parallel using a separate OS account, machine, or Docker data directory. This is not a hypothetical concern; it is the project's own stated limitation. The release is v2.0.0-beta.28, and the README says 'v2 is currently in beta' and 'after its remaining release gates pass.' So the software is not production-ready by the project's own admission. If you are an engineer evaluating this for a team, you should treat it as a preview, not a stable tool. The good news is that sessions are stored in SQLite, so the data model is at least structured, but that does not guarantee a migration path from v1.

Maintenance and Upgrade Costs: What the Repo Shows

The repository is not archived, and the last push is dated 2026-08-28, with three beta releases in the same week (beta.26, beta.27, beta.28). That suggests active development, but it also means the API and protocol may still shift between betas. The README lists a plugin registry at dl.motrix.app/registry/plugins.json, which is a public JSON feed for the marketplace. If you build plugins, you will need to track changes to the manifest schema and the MDXP schemas. The license is MIT, which is permissive and allows commercial use, but you should verify the license of the bundled Electron and other dependencies yourself; the README does not list them. The CLI requires Node.js 22 or later, which is a recent version; if your environment is on an older LTS, you will need to upgrade. The headless server runs in Docker, which adds a container management layer to your upgrade process. Overall, the maintenance cost is moderate: you are tied to the beta release cadence, and the protocol schemas are the contract you must watch. There is no mention of a stable API version guarantee in the visible material.

Alternatives and Where Motrix Fits

The obvious alternative is aria2, a command-line download utility that also supports HTTP, FTP, and BitTorrent, and has a JSON-RPC interface. The difference is that aria2 is a single binary with no built-in GUI, no plugin system, and no official headless web UI; you would need to build your own frontend or use a third-party one like AriaNg. Motrix v2 gives you the web UI, the plugin sandbox, and the official CLI out of the box. Another alternative is qBittorrent, which is a full GUI application with a web UI and an API, but it is primarily a BitTorrent client, not a general download manager for HTTP and FTP. Motrix's advantage is the unified core for all protocols plus the MDXP protocol for automation. However, if you only need a simple, stable download manager and do not care about plugins or headless operation, Motrix v1 or a mature tool like Free Download Manager might be less risky. The key difference in approach is that Motrix v2 is designed as a platform, not just an app, which is both its strength and its source of complexity.

Editorial conclusion

Adopt Motrix v2 if you want a download manager that separates its core from the UI, exposes a real JSON-RPC protocol (MDXP), and lets you write sandboxed plugins in QuickJS without touching Node.js. Do not adopt it if you rely on stable v1 data or need production-grade headless operation today: the README explicitly warns that v1 migration is unvalidated and the v2 beta has not passed all release gates. Before you commit, verify that your existing downloads and settings are backed up, test in a separate OS account or Docker data directory, and confirm that the plugin registry at dl.motrix.app/registry/plugins.json is reachable from your network. Only then replace your current download tool.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes