## File: README.md

<h1>Motrix</h1>
  A modern, full-featured download manager that stays simple to use


[](https://github.com/agalwood/Motrix/releases)  

English | [简体中文](./README.zh-CN.md)

## Overview

Motrix is a clean, full-featured desktop download manager for HTTP, FTP, BitTorrent, magnet links, and more.

**Motrix Turbo** is Motrix v2, rebuilt from the ground up with Electron, React, and TypeScript while keeping the clean, straightforward experience of v1. The download core is independent of the UI. Browser extensions and command-line tools communicate with the app over **MDXP** (Motrix Download eXchange Protocol), an open protocol built on JSON-RPC 2.0, while plugins run in isolated sandboxes.

The same core powers two ways to run Motrix:

- **Desktop app:** Runs on macOS, Windows, and Linux
- **Headless server:** Runs without a desktop environment, either directly on Node.js or in Docker, and includes a web UI for NAS devices and home servers

## 🧪 Beta testing

Motrix Turbo v2 is currently in beta. After its remaining release gates pass,
download [v2.0.0-beta.19 from GitHub Releases](https://github.com/agalwood/Motrix/releases/tag/v2.0.0-beta.19)
and read the [full release notes](./docs/release-notes/2.0.0-beta.19.md) before
installing it.

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. When practical, test v2 in parallel using a separate OS
account, machine, or Docker data directory.

## Screenshots

### Dashboard


  
  
  


### Downloads


  
  
  


### Settings


  
  
  


## ✨ Features

- 🕹 Clean, intuitive interface with dark mode
- 🦄 BitTorrent downloads with per-file selection, plus magnet link support
- 📡 Built-in tracker list management with automatic updates and health checks
- 🔌 UPnP and NAT-PMP port mapping
-  🚥  Upload and download limits with multiple speed-limit profiles
-  💾  SQLite-backed sessions that restore downloads after a restart
-  📊  Customizable Dashboard with transfer stats, live activity, and task tiles
- 🔔 System notifications when downloads finish, plus an in-app notification center
- 🧩 QuickJS-based plugin sandboxing, fine-grained permissions, and an in-app marketplace
-  🌐  Chrome and Firefox extensions that hand browser downloads off to Motrix in one click
- ⌨️  Official `@motrix/cli` client for everyday shell use and AI agents
-  🐳  Docker-ready headless server with secure device-code pairing for remote CLI and agent clients
-  🎬  Extensible URL Resolver plugins for extracting media from supported sites
-  🤖  System tray integration and launch at startup
-  🌍  Simplified Chinese and English UI, with more languages planned
-  🔗  Handlers for `motrix://` and `magnet:` links, plus `.torrent` file associations

## 🧩 Ecosystem

Motrix extends beyond the desktop app with a shared protocol library, command-line client, browser extensions, and a complete plugin toolchain:

| Project | Distribution | What it does |
|---------|--------------|--------------|
| [`@motrix/mdxp`](https://github.com/motrixapp/mdxp) | npm package | Defines the shared JSON-RPC 2.0 wire schemas and Zod types for MDXP, with helpers for bidirectional connections |
| [`@motrix/cli`](https://github.com/motrixapp/cli) | npm package | Provides the `motrix` command, automatically discovers a local desktop app, and pairs with remote instances |
| Motrix Browser Extension | Browser extension | Intercepts downloads in Chrome and Firefox (Manifest V3), hands them off to Motrix, and pairs securely with the desktop app over native messaging |
| [Motrix Plugin SDK](https://github.com/motrixapp/plugin-sdk) | Four npm packages | Includes `@motrix/plugin-manifest-schema`, `@motrix/plugin-api`, `@motrix/plugin-cli`, and `create-motrix-plugin` for developing, testing, and packaging plugins |
| [Builtin Plugins](https://github.com/motrixapp/builtin-plugins) | Signed `.moext` packages | Includes three official plugins: **Filename Template** for renaming files from a template before they are saved, **Page Scraper** for extracting direct file links from HTML pages, and **URL Resolver** as the foundation for site-specific media resolution |
| Plugin Registry | Public JSON feed | Publishes plugin listings and install metadata at `dl.motrix.app/registry/plugins.json` for both the website and the in-app marketplace |

### CLI quick start

```bash
npm install @motrix/cli    # Requires Node.js 22 or later

motrix add https://example.com/file.iso --save-dir ~/Downloads
motrix list                   # List downloads
motrix watch --stats          # Stream live progress as NDJSON
motrix pair --name my-nas     # Pair with a remote or headless instance
```

### Build a plugin

The [Motrix Plugin SDK](https://github.com/motrixapp/plugin-sdk) provides the TypeScript API, manifest schema, project scaffolder, and CLI used throughout the plugin development workflow:

```bash
pnpm create motrix-plugin my-plugin
cd my-plugin && pnpm install
pnpm dev                         # Watch-build and launch Motrix with the plugin
pnpm exec motrix-plugin validate # Validate motrix-plugin.json
pnpm run pack                    # Create dist/-<version>.moext
pnpm exec motrix-plugin lint     # Check the packed bundle
```

The default scaffold starts with a `beforeCreate` URL resolver. Pass `post-action` after the project name to start with an `afterComplete` notification plugin instead. Plugins can hook into `beforeCreate`, `beforeFinalize`, `afterComplete`, and `onError`, contribute callable commands and settings, and access the runtime through the `motrix:plugin-api` virtual module.

Plugins are bundled as a single ES2020 module and run inside a QuickJS sandbox without Node.js APIs or direct file and network access. Declare activation events, required capabilities, and URL-scoped host permissions in `motrix-plugin.json`; Motrix shows those requests to the user before granting access. See the [Plugin SDK documentation](https://github.com/motrixapp/plugin-sdk) for templates, the manifest and runtime API references, localization, sandbox constraints, packaging, and distribution.

##  📦  Installation

### Desktop app

Download Motrix from [motrix.app](https://motrix.app) and choose the package for your operating system. Most Mac users should choose the Apple Silicon build; Intel builds are available for older Macs with Intel processors.

After the remaining release gates pass, the current beta desktop packages
will be distributed through the GitHub prerelease linked above. Snap is not
published for this beta; prerelease tag runs stop after source validation and
do not build or publish Snap artifacts. Choose the package that matches your
operating system and architecture:

| Platform | Architectures | Packages / channel | Recommendation |
|----------|---------------|--------------------|----------------|
| macOS 12+ | `arm64` (Apple Silicon), `x64` (Intel) | `.dmg` / `.zip` | Use the `.dmg` matching your Mac; choose `x64` only for an Intel-based Mac |
| Windows | `x64` | `.exe` (NSIS installer) / `.zip` | Use the `.exe` installer for a normal installation or `.zip` for a manually extracted copy |
| Linux | `x64`, `arm64` | `.AppImage` / `.deb` / `.rpm` | Use the portable `.AppImage` on any distribution, `.deb` on Debian or Ubuntu, or `.rpm` on Fedora or openSUSE |

The `.AppImage` asks on first launch whether to register its desktop entry and
URL-scheme handlers under your user data directory; declining leaves your system
untouched. You can enable or remove this desktop integration at any time from
Settings → Integration.
This beta does not publish a Snap. Flatpak is validated separately
and is not published by the release tag. Windows `arm64` and all 32-bit
packages are not available. Windows `x64` packages are unsigned and may
trigger a Windows SmartScreen warning.

### Command-line client

```bash
npm install @motrix/cli
```

You can also install it from Settings → Integration → Command-line tools in the desktop app.

### Headless server with Docker

Tagged releases publish a multi-architecture Server image to Docker Hub and
GHCR. Beta releases publish only the immutable version tag and do not update
`latest`; the included `compose.yaml` keeps Server state separate from
downloaded resources:

```bash
mkdir -p motrix-data downloads
sudo chown 1000:1000 motrix-data downloads
export MOTRIX_IMAGE='docker.io/motrixapp/motrix-server:2.0.0-beta.19'
export MOTRIX_PUBLIC_URL='http://nas.example.lan:8080'
docker compose pull server
docker compose up -d --wait
```

The runtime is non-root, supports a read-only root filesystem, validates mount
permissions before accepting work, and preserves downloads, sessions, and
installed plugins across container replacement. The standard direct-LAN setup
publishes the Web service on port 8080 and MDXP on port 16801. Set
`MOTRIX_PUBLIC_URL` to the Web approval URL that remote clients can actually
reach; the Compose files do not substitute a misleading localhost URL.

If the Web approval URL is temporarily unavailable, an SSH operator can list
and approve the exact client code without exposing another port:

```bash
docker compose exec server motrix-admin pairing pending
docker compose exec server motrix-admin pairing approve ABCD-EFGH
```

Remote CLI and agent clients pair through the device-code flow. Browser
extensions pair with the desktop app through native messaging; first-time
extension pairing is not provided by the headless server. Direct HTTP is
appropriate only on a trusted LAN. Internet or untrusted-LAN access requires a
TLS reverse proxy and firewall rules around the origin ports. See the
[Docker Server deployment guide](./docs/docker-server.md) for ownership setup,
Docker Hub/GHCR image and tag selection, DSM 7 and fnOS installation, ports,
diagnostics, and backup/upgrade instructions.

##  🛠  Development

Development requires Node.js 22 or later and pnpm. Use the pnpm version specified by the `packageManager` field in `package.json`.

```bash
git clone https://github.com/agalwood/Motrix.git
cd Motrix

pnpm install     # Install dependencies, download aria2 for your platform, and rebuild native modules
pnpm start       # Start the Electron app in development mode with Vite HMR in the renderer

pnpm test        # Run the Vitest unit tests
pnpm test:e2e    # Run the Playwright E2E tests
pnpm run lint    # Run Biome checks

pnpm build       # Fetch signed built-in plugins, then build the native host and four Vite targets
```

### Preview the in-window application menu on macOS

Windows and Linux render the application menu inside the Motrix window. To
preview that chrome while developing on macOS, start the app with the preview
flag enabled:

```bash
MOTRIX_PREVIEW_MAC_MENU=1 pnpm start
```

The flag hides the main window's macOS traffic-light buttons and enables the
renderer dropdown menu. Restart the development process after changing the
flag because both Electron and Vite read it at startup.

This mode is intended for layout and command-item debugging. Electron routes
macOS role items through AppKit's native menu, so role-backed actions such as
**Window → Minimize** do not behave identically when invoked from the preview
dropdown. Validate those native role actions on Windows or Linux.

See the scripts in `package.json` for the available packaging commands. Platform-specific settings for macOS, Windows, and Linux live in `electron-builder.json`.

##  🔧  Tech stack

| Area | Stack |
|------|-------|
| Desktop shell | Electron 43 |
| UI | React 19 + Tailwind CSS 4 + shadcn/ui |
| Language | TypeScript in strict mode |
| Build system | Vite 8 with separate main, preload, worker, and renderer targets |
| Validation | Zod 4 for settings, IPC payloads, and wire schemas |
| Download engine | A Motrix-maintained fork of [aria2](https://github.com/motrixapp/aria2), bundled with the app |
| Persistence | better-sqlite3 for download session storage and recovery |
| Plugin sandbox | quickjs-emscripten |
| Server runtime | Node.js + Fastify + WebSocket |
| Internationalization | i18next + react-i18next |
| Quality tooling | Biome, Vitest, and Playwright |

The codebase has four strict layers. CI enforces the dependency boundaries between them, keeping the core portable and leaving a clear path for a future Rust rewrite:

```
renderer (React UI)
   |  IPC via window.motrix
app core (tasks, settings, plugins, bridge)
   |
engine adapter
   |
aria2 (download engine)
```

The Electron desktop app and the Node.js headless server share the same core. Platform-specific capabilities such as notifications and secret storage have separate implementations with consistent behavior.

##  📜  License

[MIT](./LICENSE) © 2018-present Dr_rOot

See [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) for third-party license information.
Release packages also include a generated dependency inventory, consolidated license texts, and an SPDX 2.3 SBOM under `legal/`.

---

## File: docs/release-notes/2.0.0-beta.1.md

# Motrix 2.0.0-beta.1

English | [简体中文](./2.0.0-beta.1.zh-CN.md)

> [!IMPORTANT]
> This release attempt did not complete. Both tag-triggered pipelines stopped
> before external distribution, so beta.1 has no GitHub Release, R2 update
> feed, Docker Hub or GHCR image, or Snap Store revision. Use
> [Motrix 2.0.0-beta.2](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.2/docs/release-notes/2.0.0-beta.2.md)
> instead. The remaining sections are retained as a historical record of the
> intended beta.1 scope.

Motrix 2.0.0-beta.1 was intended to be the first public beta of Motrix Turbo,
the rebuilt v2 desktop app and headless server. Its planned scope covered the
shared download core, MDXP integrations, and sandboxed plugin system.

## Highlights

- A ground-up desktop rebuild with Electron 43, React 19, and TypeScript 7,
  including a customizable Dashboard, dark mode, a cross-platform application
  menu, and clearer task-inspector feedback.
- One host-neutral download core for both the desktop app and the new Node/Web
  Server, with SQLite session recovery, tracker management, UPnP/NAT-PMP, and
  HTTP, FTP, BitTorrent, and magnet support.
- MDXP-based integration for the official CLI and browser handoff, including
  secure local discovery and device-code pairing for remote Server instances.
- A QuickJS plugin sandbox with capability consent, signed builtin plugins,
  and an in-app plugin marketplace.
- Persistent, multi-architecture Server containers for NAS and home-server
  deployments, with publication planned for Docker Hub and GHCR.
- A rebuilt release pipeline with isolated macOS signing, optional Windows
  Authenticode signing, package verification, third-party notices, and an SPDX
  SBOM.

## Before testing

This is prerelease software. Back up your existing Motrix application data and
downloads before installing it. Migration from Motrix v1 data has not yet been
validated, so do not use your only copy of v1 data with this beta.

When practical, test v2 in parallel using a separate OS account, machine, or
Docker data directory. Please do not rely on this beta for your only copy of
important downloads.

## What to test

- HTTP, FTP, BitTorrent, and magnet downloads, including pause/resume and
  session recovery
- Desktop integrations, browser and CLI handoff through MDXP, and sandboxed
  plugins
- Headless Server deployment, persistent storage, and remote pairing

## Intended downloads (not published)

| Distribution | Architectures | Intended output |
|--------------|---------------|------------------|
| macOS 12 or later | `arm64` (Apple Silicon), `x64` (Intel) | DMG and ZIP |
| Windows | `x64` | NSIS installer (`.exe`) and ZIP |
| Linux | `x64`, `arm64` | DEB and RPM |
| Docker Hub / GHCR | `linux/amd64`, `linux/arm64` | Immutable `2.0.0-beta.1` tag in both registries |
| Snap Store | `amd64`, `arm64` | `latest/edge` |

The planned container image names were
`docker.io/motrixapp/motrix-server:2.0.0-beta.1` and
`ghcr.io/agalwood/motrix-server:2.0.0-beta.1`; they were not published. See the
[Docker Server deployment guide](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.1/docs/docker-server.md)
for storage, networking, and upgrade guidance.

## Known distribution limits

- AppImage is not published for this beta.
- Flatpak is validated separately and is not published by the release tag.
- Windows `arm64` and all 32-bit packages are not available.
- The intended Windows packages would not have been Authenticode-signed and
  could have triggered a Windows SmartScreen warning. No beta.1 Windows
  package was published.
- Beta container tags are immutable and do not update `latest`, `stable`, or
  other stable floating tags.

## Feedback

Please report reproducible problems through
[GitHub Issues](https://github.com/agalwood/Motrix/issues). Include your
operating system, architecture, package type, and the steps needed to reproduce
the issue.

---

## File: docs/release-notes/2.0.0-beta.1.zh-CN.md

# Motrix 2.0.0-beta.1

[English](./2.0.0-beta.1.md) | 简体中文

> [!IMPORTANT]
> 本次发布尝试未完成：两条由 tag 触发的流水线均在对外分发前停止，
> 因此 beta.1 没有 GitHub Release、R2 更新数据源、Docker Hub 或 GHCR
> 镜像，也没有 Snap Store revision。请改用
> [Motrix 2.0.0-beta.2](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.2/docs/release-notes/2.0.0-beta.2.zh-CN.md)。
> 下文仅作为 beta.1 原定范围的历史记录保留。

Motrix 2.0.0-beta.1 原计划作为 Motrix Turbo 的首个公开 beta，其原定范围
包含重新开发的 v2 桌面应用和 Headless server、共用下载内核、MDXP 集成
和沙箱化插件系统。

## 主要变化

- 使用 Electron 43、React 19 和 TypeScript 7 从头重建桌面应用，提供可自定义
  Dashboard、深色模式、跨平台应用菜单，以及更清晰的任务检查器反馈。
- 桌面应用和全新的 Node/Web Server 共用与宿主无关的下载内核，支持 SQLite
  session 恢复、Tracker 管理、UPnP/NAT-PMP，以及 HTTP、FTP、BitTorrent 和
  磁力链接下载。
- 官方 CLI 和浏览器任务交接统一使用 MDXP，并支持本地安全发现及远程 Server
  的 device-code 配对。
- 提供带能力授权的 QuickJS 插件沙箱、已签名的内置插件和应用内插件市场。
- 面向 NAS 和家庭服务器提供持久化、多架构 Server 容器，原计划同时发布到
  Docker Hub 与 GHCR。
- 重建发布流水线，隔离 macOS 签名步骤、支持可选的 Windows Authenticode
  签名，并加入安装包验证、第三方声明和 SPDX SBOM。

## 测试前须知

这是预发布软件。安装前请备份现有 Motrix 应用数据和下载文件。Motrix v1
数据的迁移路径尚未经过验证，请勿让本 beta 使用您唯一一份 v1 数据。

条件允许时，建议通过独立的系统账户、设备或 Docker 数据目录与现有环境
并行测试 v2。请勿让本 beta 成为重要下载文件的唯一存储位置。

## 建议测试项

- HTTP、FTP、BitTorrent 和磁力链接下载，包括暂停/继续与 session 恢复
- 桌面集成、通过 MDXP 进行的浏览器和 CLI 任务交接，以及沙箱化插件
- Headless Server 部署、数据持久化和远程配对

## 原计划下载（未发布）

| 发布方式 | 架构 | 原计划产物 |
|----------|------|----------|
| macOS 12 或更高版本 | `arm64`（Apple Silicon）、`x64`（Intel） | DMG 和 ZIP |
| Windows | `x64` | NSIS 安装包（`.exe`）和 ZIP |
| Linux | `x64`、`arm64` | DEB 和 RPM |
| Docker Hub / GHCR | `linux/amd64`、`linux/arm64` | 两个 registry 中均发布不可变 tag `2.0.0-beta.1` |
| Snap Store | `amd64`、`arm64` | `latest/edge` |

原计划的容器镜像地址为 `docker.io/motrixapp/motrix-server:2.0.0-beta.1` 和
`ghcr.io/agalwood/motrix-server:2.0.0-beta.1`，但它们并未发布。数据持久化、网络和升级方法请参阅
[Docker Server 部署指南](../docker-server.zh-CN.md)。

## 已知发布限制

- 本 beta 不发布 AppImage。
- Flatpak 会单独验证，不会随该版本 tag 发布。
- 不提供 Windows `arm64` 和任何 32 位安装包。
- 原计划的 Windows 安装包不会进行 Authenticode 签名，因而可能触发
  Windows SmartScreen 警告。beta.1 实际并未发布 Windows 安装包。
- Beta 容器 tag 不可变，不会更新 `latest`、`stable` 或其他稳定版浮动 tag。

## 反馈

请通过 [GitHub Issues](https://github.com/agalwood/Motrix/issues) 报告可复现的问题，
并附上操作系统、架构、安装包类型和复现步骤。

---

## File: docs/release-notes/2.0.0-beta.2.md

# Motrix 2.0.0-beta.2

English | [简体中文](./2.0.0-beta.2.zh-CN.md)

> [!IMPORTANT]
> This release attempt did not complete. The four non-Windows build targets
> succeeded, but the Windows job stopped while creating its isolated signing
> input because PowerShell did not expand the Bash-style `$GITHUB_SHA`
> reference. The Snap run was canceled before its Store publish job began.
> Beta.2 created no GitHub Release, R2 update feed, Docker Hub or GHCR image,
> or Snap Store revision. Use
> [Motrix 2.0.0-beta.3](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.3/docs/release-notes/2.0.0-beta.3.md)
> instead. The remaining sections are retained as a historical record of the
> intended beta.2 scope.

Motrix 2.0.0-beta.2 was intended to be the first publicly distributed Motrix
Turbo beta. Its planned scope covered the rebuilt v2 desktop app and headless
server, shared download core, MDXP integrations, and sandboxed plugin system.

## Release recovery fixes included

- Corrected Electron runtime dependency hydration so the packaged desktop app
  contains the runtime modules required when it launches.
- Corrected Snap artifact staging so the tag pipeline can verify and publish
  the exact `amd64` and `arm64` build outputs.

## Highlights

- A ground-up desktop rebuild with Electron 43, React 19, and TypeScript 7,
  including a customizable Dashboard, dark mode, a cross-platform application
  menu, and clearer task-inspector feedback.
- One host-neutral download core for both the desktop app and the new Node/Web
  Server, with SQLite session recovery, tracker management, UPnP/NAT-PMP, and
  HTTP, FTP, BitTorrent, and magnet support.
- MDXP-based integration for the official CLI and browser handoff, including
  secure local discovery and device-code pairing for remote Server instances.
- A QuickJS plugin sandbox with capability consent, signed builtin plugins,
  and an in-app plugin marketplace.
- Persistent, multi-architecture Server containers for NAS and home-server
  deployments, with publication planned for Docker Hub and GHCR.
- A rebuilt release pipeline with isolated macOS signing, explicit unsigned
  Windows finalization, package verification, third-party notices, and an SPDX
  SBOM.

## Planned testing precautions

This is prerelease software. Back up your existing Motrix application data and
downloads before installing it. Migration from Motrix v1 data has not yet been
validated, so do not use your only copy of v1 data with this beta.

When practical, test v2 in parallel using a separate OS account, machine, or
Docker data directory. Please do not rely on this beta for your only copy of
important downloads.

## Planned testing

- HTTP, FTP, BitTorrent, and magnet downloads, including pause/resume and
  session recovery
- Desktop integrations, browser and CLI handoff through MDXP, and sandboxed
  plugins
- Headless Server deployment, persistent storage, and remote pairing

## Intended downloads (not published)

| Distribution | Architectures | Intended output |
|--------------|---------------|------------------|
| macOS 12 or later | `arm64` (Apple Silicon), `x64` (Intel) | DMG and ZIP |
| Windows | `x64` | NSIS installer (`.exe`) and ZIP |
| Linux | `x64`, `arm64` | DEB and RPM |
| Docker Hub / GHCR | `linux/amd64`, `linux/arm64` | Immutable `2.0.0-beta.2` tag in both registries |
| Snap Store | `amd64`, `arm64` | `latest/edge` |

The planned container image names were
`docker.io/motrixapp/motrix-server:2.0.0-beta.2` and
`ghcr.io/agalwood/motrix-server:2.0.0-beta.2`; they were not published. See the
[Docker Server deployment guide](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.2/docs/docker-server.md)
for storage, networking, and upgrade guidance.

## Known distribution limits

- AppImage was not published for this beta.
- Flatpak was validated separately and was not published by the release tag.
- Windows `arm64` and all 32-bit packages are not available.
- The intended Windows packages would not have been Authenticode-signed and
  could have triggered a Windows SmartScreen warning. No beta.2 Windows
  package was published.
- The planned beta container tags were immutable and would not have updated
  `latest`, `stable`, or other stable floating tags.

## Feedback

Please report reproducible problems through
[GitHub Issues](https://github.com/agalwood/Motrix/issues). Include your
operating system, architecture, package type, and the steps needed to reproduce
the issue.

---

## File: docs/release-notes/2.0.0-beta.2.zh-CN.md

# Motrix 2.0.0-beta.2

[English](./2.0.0-beta.2.md) | 简体中文

> [!IMPORTANT]
> 本次发布尝试未完成。4 个非 Windows 构建目标均已成功，但 Windows job 在创建
> 隔离的签名输入时停止，原因是 PowerShell 没有展开 Bash 形式的
> `$GITHUB_SHA` 引用。Snap 流水线在 Store 发布 job 开始前被取消。
> beta.2 未创建 GitHub Release，也未发布 R2 更新数据源、Docker Hub
> 或 GHCR 镜像及 Snap Store revision。请改用
> [Motrix 2.0.0-beta.3](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.3/docs/release-notes/2.0.0-beta.3.zh-CN.md)。
> 下文仅作为 beta.2 原定范围的历史记录保留。

Motrix 2.0.0-beta.2 原计划作为首个对外分发的 Motrix Turbo beta。
其原定范围包含重新开发的 v2 桌面应用和 Headless server、共用下载内核、
MDXP 集成和沙箱化插件系统。

## 已包含的发布恢复修复

- 修正 Electron runtime 依赖的补全流程，确保打包后的桌面应用包含启动时所需
  的 runtime module。
- 修正 Snap 产物的 staging 流程，使 tag 流水线能够验证并发布确定的
  `amd64` 和 `arm64` 构建产物。

## 主要变化

- 使用 Electron 43、React 19 和 TypeScript 7 从头重建桌面应用，提供可自定义
  Dashboard、深色模式、跨平台应用菜单，以及更清晰的任务检查器反馈。
- 桌面应用和全新的 Node/Web Server 共用与宿主无关的下载内核，支持 SQLite
  session 恢复、Tracker 管理、UPnP/NAT-PMP，以及 HTTP、FTP、BitTorrent 和
  磁力链接下载。
- 官方 CLI 和浏览器任务交接统一使用 MDXP，并支持本地安全发现及远程 Server
  的 device-code 配对。
- 提供带能力授权的 QuickJS 插件沙箱、已签名的内置插件和应用内插件市场。
- 面向 NAS 和家庭服务器提供持久化、多架构 Server 容器，原计划同时发布到
  Docker Hub 与 GHCR。
- 重建发布流水线，隔离 macOS 签名步骤，并明确支持未签名的 Windows
  最终处理，同时加入安装包验证、第三方声明和 SPDX SBOM。

## 原计划的测试须知

这是预发布软件。安装前请备份现有 Motrix 应用数据和下载文件。Motrix v1
数据的迁移路径尚未经过验证，请勿让本 beta 使用您唯一一份 v1 数据。

条件允许时，建议通过独立的系统账户、设备或 Docker 数据目录与现有环境
并行测试 v2。请勿让本 beta 成为重要下载文件的唯一存储位置。

## 原计划的测试项

- HTTP、FTP、BitTorrent 和磁力链接下载，包括暂停/继续与 session 恢复
- 桌面集成、通过 MDXP 进行的浏览器和 CLI 任务交接，以及沙箱化插件
- Headless Server 部署、数据持久化和远程配对

## 原计划下载（未发布）

| 发布方式 | 架构 | 原计划产物 |
|----------|------|----------|
| macOS 12 或更高版本 | `arm64`（Apple Silicon）、`x64`（Intel） | DMG 和 ZIP |
| Windows | `x64` | NSIS 安装包（`.exe`）和 ZIP |
| Linux | `x64`、`arm64` | DEB 和 RPM |
| Docker Hub / GHCR | `linux/amd64`、`linux/arm64` | 两个 registry 中均发布不可变 tag `2.0.0-beta.2` |
| Snap Store | `amd64`、`arm64` | `latest/edge` |

原计划的容器镜像地址为 `docker.io/motrixapp/motrix-server:2.0.0-beta.2` 和
`ghcr.io/agalwood/motrix-server:2.0.0-beta.2`，但它们并未发布。数据持久化、网络和升级方法请参阅
[Docker Server 部署指南](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.2/docs/docker-server.zh-CN.md)。

## 已知发布限制

- 本 beta 未发布 AppImage。
- Flatpak 已单独验证，未随该版本 tag 发布。
- 不提供 Windows `arm64` 和任何 32 位安装包。
- 原计划的 Windows 安装包不会进行 Authenticode 签名，因而可能触发
  Windows SmartScreen 警告。beta.2 实际并未发布 Windows 安装包。
- 原计划的 beta 容器 tag 不可变，不会更新 `latest`、`stable` 或其他稳定版
  浮动 tag。

## 反馈

请通过 [GitHub Issues](https://github.com/agalwood/Motrix/issues) 报告可复现的问题，
并附上操作系统、架构、安装包类型和复现步骤。

---

## File: docs/release-notes/2.0.0-beta.3.md

# Motrix 2.0.0-beta.3

English | [简体中文](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.4/docs/release-notes/2.0.0-beta.3.zh-CN.md)

> [!IMPORTANT]
> This release attempt did not complete. The four non-Windows desktop build
> targets (macOS `arm64`/`x64` and Linux `arm64`/`x64`) succeeded. The corrected
> signing-input handoff delivered the complete triggering commit to Windows,
> but Git checkout converted fixed-digest UTF-8 control files from LF to CRLF.
> `electron-builder.signing.json` was the first fixed SHA-256 mismatch; the
> audit found the same byte conversion in other digest-pinned control text and
> the embedded verifier. Signing-input creation failed closed before a Windows
> signing input was uploaded.
>
> Windows finalization, both macOS finalize jobs, assemble, GitHub Release, R2
> update-feed publishing, and container publishing never ran. Snap completed
> and staged verified `amd64` and `arm64` artifacts, but its Store publish job
> was canceled with `steps=[]` before credential validation. It performed no
> Store upload, `latest/edge` release, or public verification. Beta.3 therefore
> created no GitHub Release, R2 feed, Docker Hub or GHCR image, or Snap Store
> revision: external distribution remained zero. Use
> [Motrix 2.0.0-beta.4](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.4/docs/release-notes/2.0.0-beta.4.md)
> instead. The remaining sections are retained as a historical record of the
> intended beta.3 scope.

Motrix 2.0.0-beta.3 was intended to be the first publicly distributed Motrix
Turbo beta. Its planned scope covered the rebuilt v2 desktop app and headless
server, shared download core, MDXP integrations, and sandboxed plugin system.

## Release recovery fixes included

- Corrected the Windows signing-input handoff so the complete triggering
  commit metadata reached isolated finalization.
- Corrected Electron runtime dependency hydration so the packaged desktop app
  contains the runtime modules required when it launches.
- Corrected Snap artifact staging so the tag pipeline could verify and stage
  the exact `amd64` and `arm64` build outputs.

## Highlights

- A ground-up desktop rebuild with Electron 43, React 19, and TypeScript 7,
  including a customizable Dashboard, dark mode, a cross-platform application
  menu, and clearer task-inspector feedback.
- One host-neutral download core for both the desktop app and the new Node/Web
  Server, with SQLite session recovery, tracker management, UPnP/NAT-PMP, and
  HTTP, FTP, BitTorrent, and magnet support.
- MDXP-based integration for the official CLI and browser handoff, including
  secure local discovery and device-code pairing for remote Server instances.
- A QuickJS plugin sandbox with capability consent, signed builtin plugins,
  and an in-app plugin marketplace.
- Persistent, multi-architecture Server containers for NAS and home-server
  deployments, with publication planned for Docker Hub and GHCR.
- A rebuilt release pipeline with isolated macOS signing, explicit unsigned
  Windows finalization, package verification, third-party notices, and an SPDX
  SBOM.

## Planned testing precautions

This is prerelease software. Back up your existing Motrix application data and
downloads before installing it. Migration from Motrix v1 data has not yet been
validated, so do not use your only copy of v1 data with this beta.

When practical, test v2 in parallel using a separate OS account, machine, or
Docker data directory. Please do not rely on this beta for your only copy of
important downloads.

## Planned testing

- HTTP, FTP, BitTorrent, and magnet downloads, including pause/resume and
  session recovery
- Desktop integrations, browser and CLI handoff through MDXP, and sandboxed
  plugins
- Headless Server deployment, persistent storage, and remote pairing

## Intended downloads (not published)

| Distribution | Architectures | Intended output |
|--------------|---------------|-----------------|
| macOS 12 or later | `arm64` (Apple Silicon), `x64` (Intel) | DMG and ZIP |
| Windows | `x64` | NSIS installer (`.exe`) and ZIP |
| Linux | `x64`, `arm64` | DEB and RPM |
| Docker Hub / GHCR | `linux/amd64`, `linux/arm64` | Immutable `2.0.0-beta.3` tag in both registries |
| Snap Store | `amd64`, `arm64` | `latest/edge` |

The planned container image names were
`docker.io/motrixapp/motrix-server:2.0.0-beta.3` and
`ghcr.io/agalwood/motrix-server:2.0.0-beta.3`; they were not published. See the
[Docker Server deployment guide](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.3/docs/docker-server.md)
for storage, networking, and upgrade guidance.

## Known distribution limits

- AppImage was not published for this beta.
- Flatpak was validated separately and was not published by the release tag.
- Windows `arm64` and all 32-bit packages are not available.
- The intended Windows packages would not have been Authenticode-signed and
  could have triggered a Windows SmartScreen warning. No beta.3 Windows
  package was published.
- The planned beta container tags were immutable and would not have updated
  `latest`, `stable`, or other stable floating tags.

## Feedback

Please report reproducible problems through
[GitHub Issues](https://github.com/agalwood/Motrix/issues). Include your
operating system, architecture, package type, and the steps needed to reproduce
the issue.

---

## File: docs/release-notes/2.0.0-beta.3.zh-CN.md

# Motrix 2.0.0-beta.3

[English](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.4/docs/release-notes/2.0.0-beta.3.md) | 简体中文

> [!IMPORTANT]
> 本次发布尝试未完成。4 个非 Windows 桌面构建目标（macOS `arm64`/`x64`
> 和 Linux `arm64`/`x64`）均已成功。修正后的 signing-input 交接已把完整的
> 触发 commit 信息传到 Windows，但 Git checkout 将固定摘要的 UTF-8 控制文件
> 从 LF 转为 CRLF。`electron-builder.signing.json` 首先触发固定 SHA-256
> 不匹配；审计确认其他受摘要保护的控制文本和内嵌 verifier 也发生了相同的
> 字节转换。signing-input 创建流程在上传 Windows 签名输入前 fail closed。
>
> Windows finalize、两个 macOS finalize job、assemble、GitHub Release、R2
> 更新数据源发布和 container publish 均未执行。Snap 完成并暂存了经过验证的
> `amd64` 和 `arm64` 产物，但 Store publish job 在 credential validation 前以
> `steps=[]` 状态取消，没有执行 Store upload、`latest/edge` release 或 public
> verification。因此 beta.3 未创建 GitHub Release、R2 数据源、Docker Hub 或
> GHCR 镜像及 Snap Store revision，外部分发为零。请改用
> [Motrix 2.0.0-beta.4](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.4/docs/release-notes/2.0.0-beta.4.zh-CN.md)。
> 下文仅作为 beta.3 原定范围的历史记录保留。

Motrix 2.0.0-beta.3 原计划作为首个对外分发的 Motrix Turbo beta。
其原定范围包含重新开发的 v2 桌面应用和 Headless server、共用下载内核、
MDXP 集成和沙箱化插件系统。

## 已包含的发布恢复修复

- 修正 Windows signing-input 的交接流程，使完整的触发 commit 信息能够到达
  隔离的最终处理阶段。
- 修正 Electron runtime 依赖的补全流程，确保打包后的桌面应用包含启动时所需
  的 runtime module。
- 修正 Snap 产物的 staging 流程，使 tag 流水线能够验证并暂存确定的
  `amd64` 和 `arm64` 构建产物。

## 主要变化

- 使用 Electron 43、React 19 和 TypeScript 7 从头重建桌面应用，提供可自定义
  Dashboard、深色模式、跨平台应用菜单，以及更清晰的任务检查器反馈。
- 桌面应用和全新的 Node/Web Server 共用与宿主无关的下载内核，支持 SQLite
  session 恢复、Tracker 管理、UPnP/NAT-PMP，以及 HTTP、FTP、BitTorrent 和
  磁力链接下载。
- 官方 CLI 和浏览器任务交接统一使用 MDXP，并支持本地安全发现及远程 Server
  的 device-code 配对。
- 提供带能力授权的 QuickJS 插件沙箱、已签名的内置插件和应用内插件市场。
- 面向 NAS 和家庭服务器提供持久化、多架构 Server 容器，原计划同时发布到
  Docker Hub 与 GHCR。
- 重建发布流水线，隔离 macOS 签名步骤，并明确支持未签名的 Windows
  最终处理，同时加入安装包验证、第三方声明和 SPDX SBOM。

## 原计划的测试须知

这是预发布软件。安装前请备份现有 Motrix 应用数据和下载文件。Motrix v1
数据的迁移路径尚未经过验证，请勿让本 beta 使用您唯一一份 v1 数据。

条件允许时，建议通过独立的系统账户、设备或 Docker 数据目录与现有环境
并行测试 v2。请勿让本 beta 成为重要下载文件的唯一存储位置。

## 原计划的测试项

- HTTP、FTP、BitTorrent 和磁力链接下载，包括暂停/继续与 session 恢复
- 桌面集成、通过 MDXP 进行的浏览器和 CLI 任务交接，以及沙箱化插件
- Headless Server 部署、数据持久化和远程配对

## 原计划下载（未发布）

| 发布方式 | 架构 | 原计划产物 |
|----------|------|------------|
| macOS 12 或更高版本 | `arm64`（Apple Silicon）、`x64`（Intel） | DMG 和 ZIP |
| Windows | `x64` | NSIS 安装包（`.exe`）和 ZIP |
| Linux | `x64`、`arm64` | DEB 和 RPM |
| Docker Hub / GHCR | `linux/amd64`、`linux/arm64` | 两个 registry 中均发布不可变 tag `2.0.0-beta.3` |
| Snap Store | `amd64`、`arm64` | `latest/edge` |

原计划的容器镜像地址为 `docker.io/motrixapp/motrix-server:2.0.0-beta.3` 和
`ghcr.io/agalwood/motrix-server:2.0.0-beta.3`，但它们并未发布。数据持久化、网络和升级方法请参阅
[Docker Server 部署指南](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.3/docs/docker-server.zh-CN.md)。

## 已知发布限制

- 本 beta 未发布 AppImage。
- Flatpak 已单独验证，未随该版本 tag 发布。
- 不提供 Windows `arm64` 和任何 32 位安装包。
- 原计划的 Windows 安装包不会进行 Authenticode 签名，因而可能触发
  Windows SmartScreen 警告。beta.3 实际并未发布 Windows 安装包。
- 原计划的 beta container tag 不可变，不会更新 `latest`、`stable` 或其他
  稳定版浮动 tag。

## 反馈

请通过 [GitHub Issues](https://github.com/agalwood/Motrix/issues) 报告可复现的问题，
并附上操作系统、架构、安装包类型和复现步骤。

---

## File: docs/release-notes/2.0.0-beta.4.md

# Motrix 2.0.0-beta.4

English | [简体中文](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.5/docs/release-notes/2.0.0-beta.4.zh-CN.md)

> [!IMPORTANT]
> This release attempt did not complete. All five desktop build jobs—macOS
> `arm64`/`x64`, Windows `x64`, and Linux `arm64`/`x64`—succeeded. The Windows
> LF-pinning fix kept all ten digest-pinned signing control texts in canonical
> LF form, and their fixed SHA-256 checks passed.
>
> Isolated Windows finalization then failed closed before any Authenticode
> secret was read. The real signing manifest contained 2,434 unique entries in
> directory-first DFS order, while the verifier required full-path dictionary
> order for every canonical relative path. The first inversion placed an entry
> below `js-yaml/lib/schema/…` before its sibling file
> `js-yaml/lib/schema.js`; the manifest contained no duplicate entries.
>
> The macOS signing environments were not approved, and both macOS finalization
> jobs were canceled. Assemble, GitHub Release, R2 update-feed publishing, and
> container publishing never ran. Snap successfully built, verified, and
> uploaded the `arm64` GitHub Actions artifact; its `amd64` build was canceled
> during the strict Snap build. The Store publish job ended with `steps=[]`, so
> nested artifact staging, Store credential validation, Store upload,
> `latest/edge` release, and public verification never ran.
>
> Beta.4 therefore created no GitHub Release, R2 feed, Docker Hub or GHCR image,
> or Snap Store revision: external distribution remained zero. Use
> [Motrix 2.0.0-beta.5](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.5/docs/release-notes/2.0.0-beta.5.md)
> instead. The remaining sections are retained as a historical record of the
> intended beta.4 scope.

Motrix 2.0.0-beta.4 was intended to begin public validation of the rebuilt v2
desktop app and headless server, shared download core, MDXP integrations, and
sandboxed plugin system.

## Release recovery fixes included

- Declared all ten digest-pinned isolated signing control text paths as
  `text eol=lf` in `.gitattributes`, preserving canonical LF bytes across
  Windows checkouts without weakening raw-byte SHA-256 verification.
- Preserved the complete triggering commit metadata in the Windows
  signing-input handoff before isolated finalization.
- Hydrated Electron runtime dependencies so the packaged desktop app contained
  the modules required when it launched.
- Staged the exact verified `amd64` and `arm64` Snap artifacts before Store
  publication.

## Highlights

- A ground-up desktop rebuild with Electron 43, React 19, and TypeScript 7,
  including a customizable Dashboard, dark mode, a cross-platform application
  menu, and clearer task-inspector feedback.
- One host-neutral download core for both the desktop app and the new Node/Web
  Server, with SQLite session recovery, tracker management, UPnP/NAT-PMP, and
  HTTP, FTP, BitTorrent, and magnet support.
- MDXP-based integration for the official CLI and browser handoff, including
  secure local discovery and device-code pairing for remote Server instances.
- A QuickJS plugin sandbox with capability consent, signed builtin plugins,
  and an in-app plugin marketplace.
- Persistent, multi-architecture Server containers for NAS and home-server
  deployments, with publication planned for Docker Hub and GHCR.
- A rebuilt release pipeline with isolated macOS signing, explicit unsigned
  Windows finalization, package verification, third-party notices, and an SPDX
  SBOM.

## Planned testing precautions

This is prerelease software. Back up your existing Motrix application data and
downloads before installing it. Migration from Motrix v1 data has not yet been
validated, so do not use your only copy of v1 data with this beta.

When practical, test v2 in parallel using a separate OS account, machine, or
Docker data directory. Please do not rely on this beta for your only copy of
important downloads.

## Planned testing

- HTTP, FTP, BitTorrent, and magnet downloads, including pause/resume and
  session recovery
- Desktop integrations, browser and CLI handoff through MDXP, and sandboxed
  plugins
- Headless Server deployment, persistent storage, and remote pairing

## Intended downloads (not published)

| Distribution | Architectures | Intended output |
|--------------|---------------|-----------------|
| macOS 12 or later | `arm64` (Apple Silicon), `x64` (Intel) | DMG and ZIP |
| Windows | `x64` | NSIS installer (`.exe`) and ZIP |
| Linux | `x64`, `arm64` | DEB and RPM |
| Docker Hub / GHCR | `linux/amd64`, `linux/arm64` | Immutable `2.0.0-beta.4` tag in both registries |
| Snap Store | `amd64`, `arm64` | `latest/edge` |

The planned container image names were
`docker.io/motrixapp/motrix-server:2.0.0-beta.4` and
`ghcr.io/agalwood/motrix-server:2.0.0-beta.4`; they were not published. See the
[Docker Server deployment guide](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.4/docs/docker-server.md)
for storage, networking, and upgrade guidance.

## Known distribution limits

- AppImage was not published for this beta.
- Flatpak was validated separately and was not published by the release tag.
- Windows `arm64` and all 32-bit packages were not available.
- The intended Windows packages would not have been Authenticode-signed and
  could have triggered a Windows SmartScreen warning. No beta.4 Windows
  package was published.
- The planned beta container tags were immutable and would not have updated
  `latest`, `stable`, or other stable floating tags.

## Feedback

Please report reproducible problems through
[GitHub Issues](https://github.com/agalwood/Motrix/issues). Include your
operating system, architecture, package type, and the steps needed to reproduce
the issue.

---

## File: docs/release-notes/2.0.0-beta.4.zh-CN.md

# Motrix 2.0.0-beta.4

[English](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.5/docs/release-notes/2.0.0-beta.4.md) | 简体中文

> [!IMPORTANT]
> 本次发布尝试未完成。5 个桌面构建 job——macOS `arm64`/`x64`、Windows
> `x64` 和 Linux `arm64`/`x64`——均已成功。Windows 的 LF 固定修复使全部
> 10 个固定摘要的签名控制文本保持 canonical LF，固定 SHA-256 校验也已通过。
>
> 隔离的 Windows finalize 随后在读取任何 Authenticode secret 前 fail closed。
> 真实签名 manifest 包含 2,434 个无重复条目，采用目录优先的 DFS 顺序；verifier
> 则要求每个 canonical 相对路径都按全路径字典序排列。首个逆序是
> `js-yaml/lib/schema/…` 下的条目排在同级文件 `js-yaml/lib/schema.js` 前；
> manifest 中没有重复条目。
>
> macOS 签名环境未获审批，两个 macOS finalize job 均被取消。assemble、
> GitHub Release、R2 更新数据源发布和 container publish 均未执行。Snap 已成功
> 构建、验证并上传 `arm64` GitHub Actions artifact；`amd64` 在 strict Snap
> build 期间取消。Store publish job 以 `steps=[]` 结束，因此 nested artifact
> staging、Store credential validation、Store upload、`latest/edge` release 和
> public verification 均未执行。
>
> 因此 beta.4 未创建 GitHub Release、R2 数据源、Docker Hub 或 GHCR 镜像及
> Snap Store revision，外部分发为零。请改用
> [Motrix 2.0.0-beta.5](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.5/docs/release-notes/2.0.0-beta.5.zh-CN.md)。
> 下文仅作为 beta.4 原定范围的历史记录保留。

Motrix 2.0.0-beta.4 原计划开始公开验证重新开发的 v2 桌面应用和 Headless
server、共用下载内核、MDXP 集成及沙箱化插件系统。

## 已包含的发布恢复修复

- 在 `.gitattributes` 中把全部 10 个固定摘要的隔离签名控制文本路径声明为
  `text eol=lf`，使 Windows checkout 保留 canonical LF 字节，同时不放宽
  原始字节 SHA-256 校验。
- 在进入隔离最终处理前，为 Windows signing-input 交接保留完整的触发 commit
  信息。
- 补全 Electron runtime 依赖，确保打包后的桌面应用包含启动时所需的 module。
- 在发布到 Store 前，暂存经过验证且确定的 `amd64` 和 `arm64` Snap 产物。

## 主要变化

- 使用 Electron 43、React 19 和 TypeScript 7 从头重建桌面应用，提供可自定义
  Dashboard、深色模式、跨平台应用菜单，以及更清晰的任务检查器反馈。
- 桌面应用和全新的 Node/Web Server 共用与宿主无关的下载内核，支持 SQLite
  session 恢复、Tracker 管理、UPnP/NAT-PMP，以及 HTTP、FTP、BitTorrent 和
  磁力链接下载。
- 官方 CLI 和浏览器任务交接统一使用 MDXP，并支持本地安全发现及远程 Server
  的 device-code 配对。
- 提供带能力授权的 QuickJS 插件沙箱、已签名的内置插件和应用内插件市场。
- 面向 NAS 和家庭服务器提供持久化、多架构 Server 容器，原计划同时发布到
  Docker Hub 与 GHCR。
- 重建发布流水线，隔离 macOS 签名步骤，并明确支持未签名的 Windows
  最终处理，同时加入安装包验证、第三方声明和 SPDX SBOM。

## 原计划的测试须知

这是预发布软件。安装前请备份现有 Motrix 应用数据和下载文件。Motrix v1
数据的迁移路径尚未经过验证，请勿让本 beta 使用您唯一一份 v1 数据。

条件允许时，建议通过独立的系统账户、设备或 Docker 数据目录与现有环境
并行测试 v2。请勿让本 beta 成为重要下载文件的唯一存储位置。

## 原计划的测试项

- HTTP、FTP、BitTorrent 和磁力链接下载，包括暂停/继续与 session 恢复
- 桌面集成、通过 MDXP 进行的浏览器和 CLI 任务交接，以及沙箱化插件
- Headless Server 部署、数据持久化和远程配对

## 原计划下载（未发布）

| 发布方式 | 架构 | 原计划产物 |
|----------|------|------------|
| macOS 12 或更高版本 | `arm64`（Apple Silicon）、`x64`（Intel） | DMG 和 ZIP |
| Windows | `x64` | NSIS 安装包（`.exe`）和 ZIP |
| Linux | `x64`、`arm64` | DEB 和 RPM |
| Docker Hub / GHCR | `linux/amd64`、`linux/arm64` | 两个 registry 中均发布不可变 tag `2.0.0-beta.4` |
| Snap Store | `amd64`、`arm64` | `latest/edge` |

原计划的容器镜像地址为 `docker.io/motrixapp/motrix-server:2.0.0-beta.4` 和
`ghcr.io/agalwood/motrix-server:2.0.0-beta.4`，但它们并未发布。数据持久化、
网络和升级方法请参阅
[Docker Server 部署指南](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.4/docs/docker-server.zh-CN.md)。

## 已知发布限制

- 本 beta 未发布 AppImage。
- Flatpak 已单独验证，未随该版本 tag 发布。
- 不提供 Windows `arm64` 和任何 32 位安装包。
- 原计划的 Windows 安装包不会进行 Authenticode 签名，因而可能触发
  Windows SmartScreen 警告。beta.4 实际并未发布 Windows 安装包。
- 原计划的 beta container tag 不可变，不会更新 `latest`、`stable` 或其他
  稳定版浮动 tag。

## 反馈

请通过 [GitHub Issues](https://github.com/agalwood/Motrix/issues) 报告可复现的问题，
并附上操作系统、架构、安装包类型和复现步骤。

---

## File: docs/release-notes/2.0.0-beta.5.md

# Motrix 2.0.0-beta.5

English | [简体中文](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.6/docs/release-notes/2.0.0-beta.5.zh-CN.md)

> [!IMPORTANT]
> This release attempt did not complete. All five desktop build jobs—macOS
> `arm64`/`x64`, Windows `x64`, and Linux `arm64`/`x64`—succeeded. The macOS
> signing environments remained pending approval, so neither macOS
> finalization job ran. The unsigned Windows finalization job was canceled
> while it was in progress. Assemble, GitHub Release, R2 update-feed
> publishing, and Docker Hub/GHCR container publishing were canceled before
> they ran.
>
> Snap validated the source and successfully built, verified, and uploaded the
> internal GitHub Actions artifacts for both `amd64` and `arm64`. The
> `publish-edge` job downloaded both artifacts, then failed in
> `Verify complete upload set` because `verify-snap-artifact.mjs` could not
> resolve its `js-yaml` dependency on the isolated publish runner
> (`ERR_MODULE_NOT_FOUND`). This happened before Store credential validation,
> Store upload, exact revision binding, `latest/edge` release, public channel
> verification, or revision record preservation.
>
> Beta.5 therefore created no GitHub Release, R2 feed, Docker Hub or GHCR image,
> or Snap Store revision: external distribution remained zero. Use
> [Motrix 2.0.0-beta.6](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.6/docs/release-notes/2.0.0-beta.6.md)
> instead. The remaining sections are retained as a historical record of the
> intended beta.5 scope.

Motrix 2.0.0-beta.5 was intended to begin public validation of the rebuilt v2
desktop app and headless server, shared download core, MDXP integrations, and
sandboxed plugin system.

The protected `v2.0.0-beta.1`, `v2.0.0-beta.2`, `v2.0.0-beta.3`, and
`v2.0.0-beta.4` attempts all stopped before external distribution. They created
no GitHub Release, R2 update feed, Docker Hub or GHCR container image, or Snap
Store revision. Beta.5 was intended to supersede those attempts; the
[beta.4 notes](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.5/docs/release-notes/2.0.0-beta.4.md)
retain the preceding failure record.

## Release recovery fixes included

- Sorts every Windows signing-input manifest into canonical code-unit order by
  its full relative path before serialization. The creator performs one global
  sort after inventory collection, and the verifier uses the same code-unit
  comparator. The complete path is the sort key, so the sibling file
  `js-yaml/lib/schema.js` precedes entries below `js-yaml/lib/schema/…` instead
  of inheriting directory-first DFS discovery order. Strict path uniqueness,
  path safety, fixed-digest verification, and fail-closed isolation remain
  unchanged.
- Keeps all ten digest-pinned isolated signing control texts byte-stable across
  Windows checkouts through their `text eol=lf` declarations in
  `.gitattributes`; raw-byte fixed SHA-256 verification remains strict.
- Preserves the complete triggering commit metadata in the Windows
  signing-input handoff before isolated finalization.
- Hydrates Electron runtime dependencies so the packaged desktop app contains
  the modules required when it launches.
- Stages the exact verified `amd64` and `arm64` Snap artifacts before Store
  publication.

## Planned highlights

- A ground-up desktop rebuild with Electron 43, React 19, and TypeScript 7,
  including a customizable Dashboard, dark mode, a cross-platform application
  menu, and clearer task-inspector feedback.
- One host-neutral download core for both the desktop app and the new Node/Web
  Server, with SQLite session recovery, tracker management, UPnP/NAT-PMP, and
  HTTP, FTP, BitTorrent, and magnet support.
- MDXP-based integration for the official CLI and browser handoff, including
  secure local discovery and device-code pairing for remote Server instances.
- A QuickJS plugin sandbox with capability consent, signed builtin plugins,
  and an in-app plugin marketplace.
- Persistent, multi-architecture Server containers for NAS and home-server
  deployments, with publication planned for Docker Hub and GHCR.
- A rebuilt release pipeline with isolated macOS signing, explicit unsigned
  Windows finalization, package verification, third-party notices, and an SPDX
  SBOM.

## Planned testing precautions

This is prerelease software. Back up your existing Motrix application data and
downloads before installing it. Migration from Motrix v1 data has not yet been
validated, so do not use your only copy of v1 data with this beta.

When practical, test v2 in parallel using a separate OS account, machine, or
Docker data directory. Please do not rely on this beta for your only copy of
important downloads.

## Planned testing

- HTTP, FTP, BitTorrent, and magnet downloads, including pause/resume and
  session recovery
- Desktop integrations, browser and CLI handoff through MDXP, and sandboxed
  plugins
- Headless Server deployment, persistent storage, and remote pairing

## Intended downloads (not published)

| Distribution | Architectures | Intended output |
|--------------|---------------|-----------------|
| macOS 12 or later | `arm64` (Apple Silicon), `x64` (Intel) | DMG and ZIP |
| Windows | `x64` | NSIS installer (`.exe`) and ZIP |
| Linux | `x64`, `arm64` | DEB and RPM |
| Docker Hub / GHCR | `linux/amd64`, `linux/arm64` | Immutable `2.0.0-beta.5` tag in both registries |
| Snap Store | `amd64`, `arm64` | `latest/edge` |

The planned container image names were
`docker.io/motrixapp/motrix-server:2.0.0-beta.5` and
`ghcr.io/agalwood/motrix-server:2.0.0-beta.5`; they were not published. See the
[Docker Server deployment guide](https://github.com/agalwood/Motrix/blob/v2.0.0-beta.5/docs/docker-server.md)
for storage, networking, and upgrade guidance.

## Known distribution limits

- AppImage was not published for this beta.
- Flatpak was validated separately and was not published by the release tag.
- Windows `arm64` and all 32-bit packages were not available.
- The intended Windows packages would not have been Authenticode-signed and
  could have triggered a Windows SmartScreen warning. No beta.5 Windows
  package was published.
- The planned beta container tags were immutable and would not have updated
  `latest`, `stable`, or other stable floating tags.

## Feedback

Please report reproducible problems through
[GitHub Issues](https://github.com/agalwood/Motrix/issues). Include your
operating system, architecture, package type, and the steps needed to reproduce
the issue.