FluxDown

Name: FluxDown
Author: zerx-lab

Container

Multi-protocol download manager with a web UI. Handles HTTP/HTTPS, FTP, BitTorrent (DHT/magnet), eD2K/Kad, HLS and DASH, with dynamic file segmentation, token-bucket rate limiting and SQLite-backed resume. Exposes an aria2-compatible JSON-RPC API. GitHub: zerx-lab/FluxDown

Source details

Repo: zerx-lab/FluxDown

Stars: 1k

Forks: 53

Language: Rust

License: AGPL-3.0

Latest: v0.2.3 · 11 days ago

Updated: 13 minutes ago

Website: fluxdown.zerx.dev/

Configuration

Type

Container

Platform

linux

Image

ghcr.io/zerx-lab/fluxdown-server:0.2.3

Ports

17800:17800/tcp

Volumes

/data/root/Downloads

Env vars

TZ=UTC

Restart

unless-stopped

Notes

First launch prints a one-time admin token to the container log: docker logs <container> 2>&1 | grep -i token. The management API and the built-in MCP endpoint both require this token. Web UI is served on port 17800.

Standalone Install

Select an install method, to see config/commands for deploying FluxDown

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

Ensure both Docker and Portainer are installed, and up-to-date
Log into your Portainer web UI
Under Settings → App Templates, paste the below URL
Head to Home → App Templates, and the list of apps will show up
Select FluxDown, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json

Show Me

More install options in our documentation, or see zerx-lab/FluxDown for app-specific guidance.

FluxDown

Downloads, Supercharged.

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

Website · Download · Changelog · FAQ · Feedback
English | 简体中文

Highlights

Up to 10x faster — Rust + Tokio engine with IDM-style dynamic segmentation
Multi-protocol — HTTP/HTTPS, FTP, BitTorrent, eD2K, HLS & DASH streaming
Browser integration — Chrome / Edge / Firefox extension with a 3-layer interception engine
AI-agent ready — built-in MCP (Model Context Protocol) server: let Claude, Cursor & other AI clients manage your downloads
Resume anywhere — full download state persisted in SQLite; survive crashes and reboots
Beautiful UI — light/dark themes, 13 color schemes, responsive three-pane layout
Clean & private — free and open source, no ads, no tracking, no account required, local-first

Features

Feature	Description
Rust-Powered Engine	Built on Rust and Tokio with zero-cost abstractions — memory-safe concurrency at maximum throughput
Smart Segmentation	Segments split dynamically at runtime; idle threads rescue slow segments, just like IDM — but smarter
Multi-Protocol	Dedicated engines for HTTP/HTTPS, FTP, BitTorrent (DHT/UPnP/magnet), eD2K (server + Kad DHT source finding, MD4 verification), HLS (AES-decrypt) and DASH
Speed Control	Token-bucket global rate limiting — download in the background without killing your browsing
Resume Anywhere	Every byte tracked in SQLite with WAL; power loss never costs you progress
Browser Integration	Three-layer download interception, streaming media sniffing, Alt+Click bypass, right-click send
MCP Server	Built-in Model Context Protocol endpoint (Streamable HTTP) with 12 tools — AI agents can add, monitor and control downloads
Beautiful Interface	shadcn-style widgets, IDM-style segment visualization, named queues, system tray
Clean & Private	Zero ads, zero telemetry lock-in, zero accounts — your data never leaves your machine

FluxDown vs. IDM

FluxDown	IDM
Price	Free & open source	$24.95 + renewals
Open source	Yes (AGPL-3.0)	No
Platforms	Windows / macOS / Linux / NAS / Android	Windows only
BitTorrent & magnet	Yes	No
eD2K / eMule links	Yes	No
HLS / DASH streaming	Yes	Partial
Dynamic segmentation	Yes	Yes
Browser extension	Chrome / Edge / Firefox	Yes
Ads & tracking	None	—

Installation

Grab the latest build from GitHub Releases or fluxdown.zerx.dev:

Platform	Packages
Windows (x64 / ARM64)	`setup.exe` installer · portable `.zip`
macOS (Intel / Apple Silicon)	`.dmg` · portable `.tar.gz`
Linux (x64)	`.AppImage` · `.deb` · Arch `.pkg.tar.zst` · portable `.tar.gz`
Android (arm64-v8a / armeabi-v7a / x8664)	per-ABI `.apk` · universal `.apk`
NAS / Server (headless, x64 / ARM64)	Docker · Synology DSM 6/7 `.spk` · QNAP `.qpkg` · OpenWrt `.ipk` · Unraid CA template · CasaOS / ZimaOS app store

Browser Extension

Install the extension so FluxDown takes over browser downloads automatically:

MCP Server (Model Context Protocol)

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

Endpoint: http://127.0.0.1:17800/mcp (local-only by default)
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

Tools (12)

Tool	Description
`downloadadd`	Create a download task (HTTP/HTTPS, FTP, magnet, BitTorrent)
`downloadlist`	List tasks with progress/speed/status, optional status filter
`downloadget`	Get a single task by ID
`downloadpause` / `downloadresume`	Pause / resume one task
`downloadpauseall` / `download``resumeall`	Pause / resume all tasks
`downloadremove`	Remove a task, optionally deleting downloaded files
`queuelist`	List named queues and their configuration
`rsslist`	List RSS subscriptions with their configuration and runtime state
`rssadd`	Subscribe to an RSS feed and start polling it on a schedule
`rssremove`	Delete an RSS subscription and the items it collected

Client configuration

{
  "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.

Architecture

Flutter renders the UI; a zero-FFI Rust engine does the heavy lifting. The two talk through Rinf signals, and the browser extension connects via Native Messaging.

flowchart TD
    EXT["Browser Extension (WXT)"] -->|Native Messaging| NMH["fluxdown_nmh"]
    NMH -->|Named Pipe / Unix socket| HUB
    UI["Flutter UI (shadcn_ui)"] <-->|Rinf signals| HUB["hub — FFI adapter"]
    HUB --> ENGINE["fluxdown_engine"]
    ENGINE --> HTTP["HTTP/HTTPS"]
    ENGINE --> FTP["FTP"]
    ENGINE --> BT["BitTorrent"]
    ENGINE --> ED2K["eD2K"]
    ENGINE --> HLS["HLS / DASH"]
    ENGINE --> DB[("SQLite")]

Layer	Tech	Path
UI	Flutter + shadcnui	`lib/`
FFI bridge	Rinf (Dart ↔ Rust signals)	`native/hub/`
Download engine	Rust + Tokio (zero FFI deps)	`native/engine/`
Browser extension	WXT + TypeScript	`fluxDown/`
Website	Astro + React	`website/`

Building from Source

Prerequisites: Flutter SDK · Rust toolchain · Rinf CLI

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

# Check your environment
rustc --version
flutter doctor

# Install the Rinf CLI (once)
cargo install rinf_cli

# Fetch dependencies & generate Dart bindings
flutter pub get
rinf gen

# Run in debug mode
flutter run

# Build a release
flutter build windows --release   # or: macos / linux

Linux system dependencies

# Debian/Ubuntu
sudo apt-get install cmake ninja-build clang pkg-config \
  libgtk-3-dev libayatana-appindicator3-dev libnotify-dev libsecret-1-dev patchelf zstd

# Arch Linux
sudo pacman -S cmake ninja clang pkgconf gtk3 libayatana-appindicator libnotify libsecret patchelf zstd

The NMH relay binary (fluxdown_nmh) is built automatically by CMake during flutter build. Distribution packages (AppImage / deb / Arch / portable) are produced by CI on every tag.

Running tests

flutter test                          # Dart tests
cargo test -p fluxdown_engine        # Rust engine tests
cargo test -p hub                    # FFI adapter tests

Contributing & Community

Bug reports / feature requests — GitHub Issues or the in-app feedback dialog
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 -- -D warnings   # Rust
flutter analyze                                     # Dart

See CONTRIBUTING.md for the full workflow.

License

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

If FluxDown saves you time, consider giving it a Star — it helps more people discover the project.
Made by zerx-lab

Serve FluxDown on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxy Domain App port Upstream

Proxying fluxdown.example.com to http://fluxdown:17800

Add this to your Caddyfile

fluxdown.example.com {
	reverse_proxy http://fluxdown:17800
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

In Portainer, go to Containers, click the container, then Logs. Or run docker logs fluxdown
Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:17800 failed: port is already allocated", something else on your server is using that port.

Find what's using it: sudo ss -tlnp | grep :17800
Stop the other service, or pick a different host port. In 17800:17800 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

Use your server's real IP: http://your-server-ip:17800. The 0.0.0.0 link Portainer shows isn't a real address.
Give it a minute after first deploy, fluxdown can take a while to initialise.
Make sure your firewall allows the port, e.g. sudo ufw allow 17800

Image won't pull

Test the pull directly on the host: docker pull ghcr.io/zerx-lab/fluxdown-server:0.2.3

"manifest unknown" means the tag no longer exists.
"toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
"no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

Check the logs right after a restart, the last few lines before it died are the useful ones.
Get the exit code with docker inspect fluxdown --format '{{.State.ExitCode}}'
Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

Bug within the app: Open an issue on zerx-lab/FluxDown
Template not working: Open an issue within the template's repo
This website not working: Open an issue on lissy93/portainer-templates

A single container

FluxDown runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.

The app image

An image is the app packed up ready to go, everything FluxDown needs bundled into one download. This template pulls ghcr.io/zerx-lab/fluxdown-server:0.2.3, which Docker fetches once and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. FluxDown's comes from the GitHub Container Registry, published by zerx-lab.

Version tags

The bit after the colon in the image name is the version tag. This one pins 0.2.3, so every redeploy gives you that exact build until you bump it yourself.

Ports

A port is the door the app answers on. A mapping like 17800:17800 means it's reachable on port 17800 of your server, where the left number is yours to change and the right one belongs to the app. It opens:

17800:17800

Volumes

A volume is where FluxDown keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

/data as a volume Docker manages for you
/root/Downloads as a volume Docker manages for you

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. FluxDown takes 1 of them, all with defaults you can leave alone or tweak:

TZ, defaults to UTC. Timezone

Restart policy

The restart policy here is unless-stopped, so Docker restarts FluxDown after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Nothing custom is set, so FluxDown sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container fluxdown. That's what you'll spot in the containers list and use in commands like docker logs fluxdown.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

FluxDown is open source, released under the AGPL-3.0 license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set FluxDown up. Add the template list to Portainer once, then deploying FluxDown is a click rather than a wall of config.

FluxDown

Source details

Configuration

Notes

Standalone Install

Install on Portainer

Template Import URL

Project Documentation

FluxDown

Downloads, Supercharged.

Highlights

Features

FluxDown vs. IDM

Installation

Browser Extension

MCP Server (Model Context Protocol)

Tools (12)

Client configuration

Architecture

Building from Source

Contributing & Community

License

Proxy configurator

Troubleshooting

Check the logs first

Port already in use

Running but the page won't load

Image won't pull

"exec format error"

Container keeps restarting

Raise an issue

Config glossary

A single container

The app image

Where the image comes from

Version tags

Ports

Volumes

Environment variables

Restart policy

Networking

Container name

Platform

Open source license

Portainer app templates

Similar apps