🔒 Safety & Trust

I built this for myself first. Then I thought, maybe someone else needs it too.

Let me be straightforward with you:

This is a wrapper, not a reimplementation. aria2-agent doesn't replace aria2 — it wraps aria2's JSON-RPC interface with safety rules that AI Agents need. The actual downloading is still done by aria2, a battle-tested open-source project with 35,000+ stars and 20+ years of history.

No backdoors. No telemetry. No data collection. None.

• 📄 One file, 959 lines. You can read the entire source code in 10 minutes. There's nowhere to hide anything.
• 🚫 Zero network calls except to your own machine. The only connection is 127.0.0.1 — your local aria2 daemon. No "phone home", no analytics, no update checks.
• 📦 Zero dependencies. Pure Python 3.8 standard library. No pip install supply chain risk. No hidden transitive dependencies. What you see is what you get.
• 🔑 Your secrets stay yours. The RPC secret token is auto-generated locally and stored in ~/.aria2_agent/state.json. It never leaves your machine.
• 🌐 The daemon only listens on localhost. --rpc-listen-all=false means no external machine can connect. Not even your LAN.
• 📝 MIT licensed. Do whatever you want with it. Read it, audit it, fork it, sell it. No strings attached.

I'm a developer who got tired of AI Agents reporting "download complete" on corrupted files. So I wrote this. That's the whole story.

🎯 The Problem

When AI Agents (Claude, GPT, Cursor, etc.) download large files using aria2c, they hit a silent killer:

Agent:  "Download this 50GB model file."
aria2c: *pre-allocates 50GB instantly*
Agent:  *checks file size* → "50GB? Download complete!"
Agent:  *tries to use the file* → 💥 CORRUPTED / INCOMPLETE

aria2's default file-allocation=prealloc creates a full-size placeholder file before any data arrives. Any agent that checks file size to determine completion gets a false positive 100% of the time.

This isn't a bug in aria2 — it's a fundamental mismatch between aria2's human-oriented design and what AI Agents need.

💡 The Solution

aria2-agent is a purpose-built CLI + MCP Server that wraps aria2's JSON-RPC interface with 10 architecturally-enforced rules:

1. Forces file-allocation=none — no phantom files, ever
2. Completes judgment via RPC only — status == "complete" AND completedLength == totalLength
3. Pure JSON output — json.loads(stdout) and you're done
4. Blocks rule circumvention — FORBIDDEN_PER_TASK_OPTS prevents per-task overrides

# One command. Agent gets clean JSON. No false positives. Ever.
python aria2cli.py add "https://example.com/model.safetensors" \
  --dir ./downloads --out model.safetensors --wait --timeout 3600

{"ok": true, "gid": "2089b056ea1d1f3c", "complete": true, "timed_out": false,
 "elapsed": 120.5, "status": "complete",
 "totalLength": "15200000000", "completedLength": "15200000000",
 "files": [{"path": "./downloads/model.safetensors", "length": "15200000000"}]}

Agent logic: if result["complete"]: done — that's it.

✨ Features

🏁 Quick Start

Prerequisites

• Python 3.8+
• aria2c in PATH (install guide)

Install

# Option 1: pip (recommended)
pip install aria2-agent

# Option 2: just download the single file — zero dependencies
curl -O https://raw.githubusercontent.com/Rehui-2006/aria2-agent/main/aria2cli.py

3-Step Usage

# Step 1: Start the RPC daemon (once per session)
python aria2cli.py start --dir ~/Downloads

# Step 2: Download and wait for completion
python aria2cli.py add "https://example.com/large_file.bin" \
  --dir ~/Downloads --out file.bin --wait --timeout 3600

# Step 3: Agent reads JSON → checks "complete" field → done

Verify Rules Are Enforced

python aria2cli.py verify

{
  "ok": true,
  "file_allocation": "none",
  "no_file_allocation_limit": "0",
  "rules_checked": {
    "rule2_file_allocation_none": true,
    "rule2_no_file_allocation_limit_zero": true,
    "rule3_completion_via_rpc_only": true,
    "rule4_no_local_file_for_judgment": true
  }
}

📖 Core Usage

Standard Download (most common)

python aria2cli.py add "https://example.com/file.zip" \
  --dir ./downloads --out file.zip --wait --timeout 3600

Large File Download (models, datasets)

python aria2cli.py add "https://huggingface.co/model.bin" \
  --dir ./models --out model.bin \
  --split 16 --wait --timeout 3600 --retries 3

• --split 16: 16 parallel connections
• --retries 3: auto-resubmit on failure (same dir+out = aria2 resume, no re-download)

Async Download (submit then poll)

# Submit, get gid
python aria2cli.py add "https://example.com/file.zip" --dir ./dl --out f.zip

# Poll later
python aria2cli.py status <gid>
python aria2cli.py wait <gid> --timeout 3600

Multi-Source Mirror

python aria2cli.py add \
  "https://mirror1.example.com/file.iso" \
  "https://mirror2.example.com/file.iso" \
  "https://mirror3.example.com/file.iso" \
  --dir ./isos --out ubuntu.iso --wait

Proxy / Custom Headers / SSL Bypass

# Via JSON options (no shell escaping issues)
python aria2cli.py add "https://example.com/file" \
  --dir ./dl --out file --wait \
  --options '{"all-proxy":"http://127.0.0.1:1080","check-certificate":"false"}'

# Or use --options-file to avoid shell quoting hell
echo '{"header":["Authorization: Bearer xxx","Referer: https://example.com"]}' > opts.json
python aria2cli.py add "https://example.com/file" \
  --dir ./dl --out file --wait --options-file opts.json

Task Management

python aria2cli.py status <gid>           # Check status (complete field = done check)
python aria2cli.py list                    # List all tasks
python aria2cli.py pause <gid>             # Pause
python aria2cli.py resume <gid>            # Resume
python aria2cli.py remove <gid>            # Remove (keeps downloaded data)
python aria2cli.py remove <gid> --force    # Force remove
python aria2cli.py stop                     # Stop daemon

🔌 MCP Server Mode

aria2-agent ships with a built-in Model Context Protocol server — 8 tools, zero config:

pip install "aria2-agent[mcp]"
python aria2cli.py mcp

MCP Tools

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "aria2-agent": {
      "command": "python",
      "args": ["-m", "aria2cli", "mcp"]
    }
  }
}

Cursor / VS Code Integration

{
  "mcp.servers": {
    "aria2-agent": {
      "command": "python",
      "args": ["aria2cli.py", "mcp"]
    }
  }
}

See docs/AGENT_INTEGRATION.md for detailed integration guides.

🛡️ The 10 Iron Rules

These rules are architecturally enforced — not guidelines, not config defaults. Violating any rule requires a rewrite.

Rule Circumvention Prevention

FORBIDDEN_PER_TASK_OPTS = {
    "file-allocation",
    "no-file-allocation-limit",
    "enable-rpc",
    "rpc-listen-port",
    "rpc-listen-all",
    "rpc-secret",
    "rpc-allow-origin-all",
}

Even if an agent passes {"file-allocation": "prealloc"} in --options, it's silently rejected with a warning. The iron rules cannot be bypassed.

📋 Exit Codes

🎯 Use Cases

Downloading AI Models

python aria2cli.py add "https://huggingface.co/llama/model.safetensors" \
  --dir ./models --split 16 --wait --timeout 7200 --retries 3

Downloading Datasets

python aria2cli.py add "https://data.example.com/dataset.tar.gz" \
  --dir ./data --out dataset.tar.gz --wait

BT / Magnet Links

python aria2cli.py add "magnet:?xt=urn:btih:..." \
  --dir ./torrents --wait --timeout 7200

Multi-Source ISO Download

python aria2cli.py add \
  "https://mirror1/ubuntu.iso" "https://mirror2/ubuntu.iso" \
  --dir ./isos --out ubuntu.iso --wait

❓ FAQ

python aria2cli.py start --external http://your-host:6800/jsonrpc

🏗️ Architecture

┌──────────────────────────────────────────────────┐
│                  AI Agent                        │
│         (Claude / GPT / Cursor / ...)            │
└──────────────┬──────────────────┬────────────────┘
               │ CLI              │ MCP
               ▼                  ▼
┌──────────────────────┐  ┌───────────────────────┐
│   aria2cli.py        │  │  MCP Server (8 tools) │
│                      │  │                       │
│  ┌────────────────┐  │  │  ┌─────────────────┐  │
│  │  10 Iron Rules │  │  │  │  FastMCP        │  │
│  │  Enforcement   │  │  │  │  Tool Registry  │  │
│  └───────┬────────┘  │  │  └───────┬─────────┘  │
│          │           │  │          │            │
│  ┌───────▼────────┐  │  │  ┌───────▼─────────┐  │
│  │  JSON-RPC      │◄─┼──┼──┤  JSON-RPC       │  │
│  │  Client        │  │  │  │  Client         │  │
│  └───────┬────────┘  │  │  └───────┬─────────┘  │
└──────────┼───────────┘  └──────────┼───────────┘
           │                         │
           ▼                         ▼
┌──────────────────────────────────────────────────┐
│            aria2c RPC Daemon                      │
│  --enable-rpc --file-allocation=none             │
│  --no-file-allocation-limit=0                    │
│  (mandatory, non-overridable)                    │
└──────────────────────────────────────────────────┘

See docs/ARCHITECTURE.md for the full design document.

📦 Installation (Detailed)

Install aria2c

Install aria2-agent

# Via pip (with MCP support)
pip install "aria2-agent[mcp]"

# Via pip (CLI only, zero deps)
pip install aria2-agent

# Or just download the single file
wget https://raw.githubusercontent.com/Rehui-2006/aria2-agent/main/aria2cli.py

🤝 Contributing

Contributions are welcome! Please read the 10 Iron Rules first — any PR that weakens a rule will be rejected.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

📝 Changelog

See CHANGELOG.md.

📄 License

MIT — see LICENSE.

📊 Dashboards

• 📋 Health Dashboard — Daily automated health check results
• 📈 Stats Dashboard — Weekly repository statistics

⭐ Star History