Motrix Download Protocols: HTTP, BitTorrent, Magnet, FTP, and SFTP Support

Motrix supports six download protocols—HTTP/HTTPS, FTP, SFTP, BitTorrent (BT), Magnet links, and Metalink—defined in the TuningContext interface and accessible via the addTask plugin API.

Motrix is a full-featured open-source download manager maintained by agalwood that handles diverse file transfer protocols through a unified engine. Understanding the supported Motrix download protocols helps developers leverage its capabilities for standard web transfers, peer-to-peer networks, and secure file transfers. The protocol definitions reside in the core type system, specifically within the TuningContext interface located in the source code.

Complete List of Supported Motrix Download Protocols

The protocol field in the TuningContext type at src/shared/types/tuning.ts (line 30) enumerates the following supported values:

• http – Handles both standard HTTP and encrypted HTTPS URLs through a single generic handler
• ftp – Standard File Transfer Protocol for traditional file transfers
• sftp – SSH File Transfer Protocol for encrypted, secure transfers
• bt – BitTorrent protocol for downloading via .torrent metadata files
• magnet – Magnet URI scheme for BitTorrent downloads without requiring a .torrent file
• metalink – XML-based Metalink files containing multiple mirrors and file checksums

Protocol Definitions in the Source Code

In src/shared/types/tuning.ts, the TuningContext interface centralizes protocol information used for performance-tuning and download-strategy decisions. This interface constrains the allowed values for the protocol field, which the download engine uses to determine routing logic and connection handling parameters.

Task validation occurs in src/shared/schemas/add-task.ts, where protocol-specific payloads are validated against strict schemas before submission to the download engine.

Adding Downloads by Protocol

Motrix exposes these protocols through the addTask function from the motrix:plugin-api module. Each protocol requires a specific payload structure when creating new download tasks.

HTTP and HTTPS Downloads

For standard web downloads, Motrix treats the http protocol value as a generic handler that accepts both http:// and https:// schemes.

import { addTask } from 'motrix:plugin-api';

// Simple HTTP/HTTPS URL
await addTask({
  url: 'https://example.com/file.zip',
  // Additional optional fields (download path, etc.) can be provided
});

BitTorrent (.torrent) Files

To initiate a BitTorrent download using a local .torrent file, provide base64-encoded torrent data along with metadata.

import { addTask } from 'motrix:plugin-api';

// Provide the base64-encoded torrent file
await addTask({
  tab: 'torrent',
  torrentMeta: {
    name: 'ubuntu-22.04.iso',
    files: [{ path: 'ubuntu-22.04.iso', length: 3000000000 }],
    // …other metadata fields
  },
  torrentBase64: 'BASE64_ENCODED_TORRENT_DATA',
});

Magnet Links

Magnet URIs enable torrent downloads without distributing .torrent files, using distributed hash table (DHT) lookup.

import { addTask } from 'motrix:plugin-api';

// Magnet URI
await addTask({
  magnet: 'magnet:?xt=urn:btih:ABCDEF1234567890...',
});

Metalink Files

Metalink downloads utilize XML descriptors that specify multiple mirrors and cryptographic checksums for verification.

import { addTask } from 'motrix:plugin-api';

// Metalink XML (as a string)
await addTask({
  url: 'https://example.com/file.metalink',
});

Summary

• Motrix supports six protocols: HTTP/HTTPS, FTP, SFTP, BitTorrent, Magnet, and Metalink
• Protocol definitions reside in the TuningContext interface at src/shared/types/tuning.ts
• The addTask function from motrix:plugin-api handles all protocol types with specific payload requirements
• HTTP protocol handler covers both unencrypted and TLS-encrypted transfers transparently
• BitTorrent requires base64-encoded file data while Magnet links use URI strings directly
• Metalink files are processed via standard URL references to XML descriptors

Frequently Asked Questions

Does Motrix support HTTPS downloads?

Yes. While the TuningContext protocol enum lists http in src/shared/types/tuning.ts, Motrix treats this as a generic HTTP handler that accepts both http:// and https:// URLs. The underlying engine automatically handles TLS encryption when parsing HTTPS links through the addTask API.

Can Motrix download magnet links without .torrent files?

Yes. The magnet protocol value exists independently from the bt protocol in the TuningContext type. You can pass magnet URIs directly to the addTask function using the magnet property, without requiring base64-encoded torrent data or local .torrent files.

What is the difference between BT and Magnet protocols in Motrix?

The bt protocol requires a .torrent file provided as base64-encoded data via the torrentBase64 field and tab: 'torrent' specification, while the magnet protocol accepts a magnet: URI string in the magnet field. Both utilize BitTorrent peer-to-peer networking, but bt includes complete metadata in the initial request, whereas magnet retrieves metadata from the swarm.

How does Motrix validate protocol-specific download tasks?

Task validation occurs in src/shared/schemas/add-task.ts, which enforces protocol-specific schemas before submission. This validation ensures HTTP URLs, torrent metadata structures, magnet URI formats, and metalink files conform to required payloads before the download engine processes them.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}