FluxDown

Downloads, Supercharged.

A blazing fast, multi-protocol download manager — the free & open-source IDM alternative.

Website · Download · Changelog · FAQ · Feedback

English | 简体中文

• Dynamic download acceleration — Rust + Tokio engine with adaptive segmentation and slow-segment rescue
• Multi-protocol — HTTP/HTTPS, FTP, BitTorrent, eD2K, HLS & DASH streaming
• One engine, multiple clients — native GPUI desktop, Kotlin Android and SwiftUI iOS apps, React Web UI and CLI
• Browser integration — Chrome / Edge / Firefox extension with a 3-layer interception engine, plus a userscript
• AI-agent ready — built-in MCP (Model Context Protocol) server: let Claude, Cursor & other AI clients manage your downloads
• Automation & remote management — RSS subscriptions, scheduled queues, webhooks, plugins and optional FluxCloud device collaboration
• Local-first — free and open source, no ads, no account required for local downloads; resumable state stored locally by default

Privacy: local downloads do not require a FluxCloud account. Cloud features are optional. Anonymous installation and daily-active statistics are controlled by analytics_enabled and can be disabled; they do not collect download/task information. This is not a zero-telemetry application.

Grab the latest build from GitHub Releases or fluxdown.com:

Install the extension so FluxDown takes over browser downloads automatically:

The extension connects to the desktop agent through Native Messaging. A Tampermonkey userscript is also available.

The current headless service is fluxdown-agent --server + fluxdownd, with an embedded Web UI. The Docker image retains the name ghcr.io/zerx-lab/fluxdown-server.

From a checkout, use the supplied Compose configuration:

docker compose -f docker/docker-compose.yml up -d

Open http://<server>:17800/ and set an access key in the first-run wizard. The key must contain 8–128 visible ASCII characters, including both a letter and a digit. Set it up on a trusted network before exposing the service; use an HTTPS reverse proxy for remote access.

• Server mode listens on 0.0.0.0:17800 by default; override it with FLUXDOWN_BIND.
• For unattended setup, supply FLUXDOWN_TOKEN through your deployment environment or secret manager, not a committed file. It initializes the key only if one has not already been set.
• Persist /data for the database, logs and access key, and /root/Downloads for downloads. The supplied Compose file uses a named data volume and docker/downloads/ on the host.
• Prefer SSD/cache storage for /data if download disks need to sleep.
• Native deployments must keep fluxdown-agent and fluxdownd in the same directory.

The fluxdown CLI connects to the running desktop or server HTTP API by default. On desktop, enable the management API in Settings → API Service first. Supply the access key via FLUXDOWN_TOKEN; use FLUXDOWN_URL or --url to select a remote server.

fluxdown ping
fluxdown add "https://example.com/file.zip"
fluxdown --json list

# Standalone mode: embed the engine instead of connecting to a service
fluxdown add --local "https://example.com/file.zip"

Standalone mode cannot share a data directory with a running engine: stop the service using that directory first.

Desktop defaults to 127.0.0.1:17800, with management API and MCP disabled until enabled. Server mode enables both by default and requires an access key. See the OpenAPI specification for the REST contract.

FluxDown ships a built-in MCP server so AI agents (Claude Desktop, Cursor, Cline, …) can manage downloads via the Model Context Protocol. It implements a stateless Streamable HTTP subset (JSON-RPC 2.0 over POST /mcp) on the same API port — no separate MCP process needed.

• Endpoint: http://127.0.0.1:17800/mcp for the default desktop configuration; use your server address for headless deployments
• Auth: Bearer token (Authorization: Bearer <token> or X-FluxDown-Token), shared with the management API
• Enable: Settings → API Service → toggle MCP endpoint (a token is generated automatically); the headless server enables it by default

{
  "mcpServers": {
    "fluxdown": {
      "url": "http://127.0.0.1:17800/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

The MCP layer is implemented in native/api/src/mcp.rs on top of the same ApiHost trait that powers the REST management API and aria2-compatible JSON-RPC.

One Rust download engine, multiple hosts and clients. Desktop uses fluxdown-desktop → fluxdown-agent → fluxdownd; headless deployments reuse the agent and daemon with a React Web UI. Native Android and iOS clients connect through UniFFI (native/mobile), using an embedded agent and daemon for local downloads or /rpc for remote hosts.

flowchart TD
    UI["GPUI desktop"] -->|"WebSocket /rpc"| AGENT["fluxdown-agent — UI gateway and desktop shell"]
    WEB["React Web UI"] -->|"WebSocket /rpc"| AGENT
    EXT["Browser Extension (WXT)"] -->|Native Messaging| NMH["fluxdown_nmh"]
    NMH --> AGENT
    CLI["fluxdown CLI"] -->|"HTTP API"| AGENT
    AGENT -->|"Authenticated JSON-RPC"| DAEMON["fluxdownd — download core"]
    DAEMON --> ENGINE["fluxdown_engine"]
    MOBILE["Native Android / iOS"] -->|"UniFFI"| CORE["fluxdown_mobile"]
    CORE -->|"embedded or remote"| AGENT
    LOCAL["fluxdown add --local"] --> ENGINE
    ENGINE --> PROTOCOLS["HTTP/HTTPS, FTP, BitTorrent, eD2K, HLS, DASH"]
    ENGINE --> DB[("SQLite / PostgreSQL")]

• Daemon owns downloads: engine, download database, queues, RSS, plugins and webhooks.
• Agent owns integration: UI gateway, FluxCloud account/sync, device collaboration, browser capture and desktop tray/lifecycle.
• Shared contracts: native/protocol defines transport-independent DTOs, methods and events; native/api exposes REST, aria2 and MCP through ApiHost, without depending on the engine.
• Engine independence: EventSink and HostSelection connect the engine to hosts. Only one engine may write to a data directory at a time; the diagram shows alternative hosts, not concurrent writers.

Start with the Rust toolchain and your platform's native build tools (MSVC on Windows, Xcode command-line tools on macOS). Linux desktop builds also need graphics, audio and tray development libraries; the maintained Ubuntu package list is in CI. Bun is needed for the Web UI. Android uses Android Studio's JBR, Android SDK/NDK and cargo-ndk; iOS uses Xcode.

# Clone the development branch (main = active development, stable = stable releases)
git clone -b main https://github.com/zerx-lab/FluxDown.git
cd FluxDown

# Build desktop UI, agent, daemon and browser relay, then launch
cargo desktop-dev

# Build only (also stages a signed development .app on macOS)
cargo desktop-dev --build-only

The launcher reuses an existing desktop/service instance rather than forcibly restarting it. Quit the UI and stop its services before testing changes to running code.

# Build the Web UI BEFORE building the agent
cd web
bun install --frozen-lockfile
bun run build
cd ..

cargo build -p fluxdown_daemon
cargo run -p fluxdown_agent --features web-ui -- --server

The web-ui feature embeds web/dist into the agent binary at compile time. After changing the frontend, rebuild the Web UI and then the agent. FLUXDOWN_WEBROOT optionally serves a directory from disk instead.

For frontend development, run cd web && bun run dev in a second terminal while the server is running: Vite listens on port 5173 and proxies backend requests to port 17800.

cargo build -p fluxdown_cli
cargo run -p fluxdown_cli -- ping

Android lives in mobile/Android; iOS lives in mobile/FluxDown. Both use the shared Rust core in native/mobile and shared translations in assets/i18n.

# Android: use Android Studio's JBR as JAVA_HOME
(cd mobile/Android && ./gradlew :core:testDebugUnitTest :bridge:testDebugUnitTest :app:assembleDebug)
# iOS: from repository root
mobile/FluxDown/scripts/build-core.sh
(cd mobile/FluxDown && xcodebuild build -project FluxDown.xcodeproj -scheme FluxDown -destination 'generic/platform=iOS Simulator')

Official Android releases use the native project's ANDROID_NATIVE_* signing credentials. They cannot be installed over the old Flutter APK; back up needed data before uninstalling the old app. The retired Flutter SDK, Rinf and hub are no longer build prerequisites. Shared assets, legacy desktop data/theme upgrade compatibility and the website's legacy theme editor remain supported.

cargo test -p fluxdown_engine        # Engine tests
cargo test -p fluxdown_api           # HTTP / aria2 / MCP contracts
cargo test -p fluxdown_agent         # Gateway / server
cargo test -p fluxdown_cli           # CLI
cd web && bun test && cd ..          # Web UI
cargo test -p fluxdown_mobile        # Shared native mobile core

• Bug reports / feature requests — GitHub Issues or the website feedback page
• QQ Group — 832143651

Pull requests are welcome! Branch off main and target main — it is the development branch, while stable only tracks stable releases (maintainers advance it from main). Before submitting, please make sure:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings

See CONTRIBUTING.md for the full workflow.

Distributed under the GNU Affero General Public License v3.0.