Aria2 Agent

What is Aria2 Agent?

Aria2 Agent is a CLI tool and MCP (Model Context Protocol) server that wraps aria2’s JSON-RPC interface with safety rules for AI Agents. It solves the false-positive completion problem caused by aria2’s default preallocation, giving agents a reliable download status via pure JSON output. It is built for developers and AI agent users who need trustworthy, large-file downloads.

How to use Aria2 Agent?

Install with pip install aria2-agent or download the single-file aria2cli.py. Ensure Python 3.8+ and aria2c are in PATH. Start the RPC daemon once per session (python aria2cli.py start --dir ~/Downloads), then submit downloads with python aria2cli.py add <URL> --dir <path> --out <file> --wait --timeout 3600. The agent reads the JSON result’s complete field. For MCP integration, run python aria2cli.py mcp and configure the server in Claude Desktop or Cursor/VS Code.

Key features of Aria2 Agent

• Forces file-allocation=none to prevent phantom files.
• Completion judged via RPC only, never local file size.
• Pure JSON output for easy agent parsing.
• Built-in 3x retry, resume, and 3600s timeout.
• MCP Server mode with 8 tools, zero configuration.
• Zero dependencies – pure Python 3.8 standard library.
• Cross-platform: Windows, Linux, macOS.
• Prevents rule circumvention with forbidden per-task options.

Use cases of Aria2 Agent

• Downloading large AI models and datasets with reliable completion reporting.
• Automating downloads in AI agent workflows (Claude, GPT, Cursor).
• Multi-source mirror downloads with automatic fallback.
• Async download management – submit, poll, pause, resume tasks.

FAQ from Aria2 Agent

How is Aria2 Agent different from using aria2c directly?

Aria2 Agent solves the false-positive completion problem where aria2c’s default preallocation creates a full-size placeholder file before data arrives. Agents checking file size get a false “complete” signal. Aria2 Agent forces file-allocation=none, checks completion via RPC only, and outputs clean JSON with a reliable complete field. It also enforces 10 architecturally‑enforced iron rules that cannot be bypassed.

What are the dependencies and runtime requirements?

Python 3.8 or higher and aria2c in PATH. The base tool has zero external dependencies – it uses only the Python standard library. For MCP Server mode, install with pip install "aria2-agent[mcp]".

Where does my data and configuration live?

The RPC daemon listens only on 127.0.0.1. The auto-generated RPC secret token is stored in ~/.aria2_agent/state.json. No data ever leaves your machine. All downloaded files are written to the directory you specify.

Does Aria2 Agent collect telemetry or phone home?

No. The only network connection is to the local aria2 daemon on 127.0.0.1. There is no telemetry, analytics, update checks, or data collection. The entire source is a single 959‑line file for easy auditing.

What transport and authentication does it use?

Aria2 Agent communicates with the local aria2 daemon via JSON