Sailing the digital seas with ease,
Fetching treasures as we please.
With *arr at helm and put.io's might,
Downloads flow through day and night.
plundrio (/ˈplʌndriˌoʊ/) is a put.io download client designed to seamlessly
integrate with the *arr stack (Sonarr, Radarr, Lidarr, etc.). Files are
automatically added to put.io and downloaded to the local disk once complete.
By using plundrio, you can benefit from faster downloads if the file is already cached by put.io, allowing you to download it locally immediately. This is especially useful if you have a low bandwidth connection, as you can easily saturate it by downloading from put.io instead of the original source. Additionally, if put.io already has the file cached, you can skip the initial download step from the origin to put.io, saving time and bandwidth. However, in all other cases, a direct download from the origin may be more beneficial, as put.io essentially performs the same download process.
plundrio makes downloading from put.io simple and automatic:
graph LR
A[*arr Application] -->|Sends download request| B[plundrio]
B -->|Adds transfer to| C[put.io]
C -->|Transfer completes| D[plundrio monitors]
D -->|Downloads files| E[Local Storage]
D -->|Cleans up| C
plundrio implements a specialized state tracking system to ensure seamless integration with *arr applications:
Transfers are only fully removed when explicitly requested via torrent-remove RPC call
Progress Calculation:
This approach ensures reliable integration with *arr applications while optimizing put.io storage usage.
Before installing plundrio, ensure you have:
go install github.com/elsbrock/plundrio/cmd/plundrio@latest
plundrio can be integrated directly into your NixOS configuration as a service:
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
plundrio.url = "github:elsbrock/plundrio";
};
outputs = { self, nixpkgs, plundrio, ... }: {
nixosConfigurations.mySystem = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
plundrio.nixosModules.default
{
services.plundrio = {
enable = true;
targetDir = "/var/lib/plundrio/downloads";
putioFolder = "plundrio";
authTokenFile = "/run/credentials/plundrio.service/token";
# Optional configurations with defaults:
# listenAddr = ":9091";
# workerCount = 4;
# logLevel = "info";
# user = "plundrio";
# group = "plundrio";
};
}
];
};
};
}
The NixOS module: - Creates a dedicated system user and group (plundrio) - Sets up a systemd service with proper security hardening - Creates the target directory with appropriate permissions - Automatically starts at boot and restarts on failure
docker run --rm -it ghcr.io/elsbrock/plundrio:latest -- --help
Make sure to expose the transmission RPC port (default 9091) and mount the download directory:
docker run -d \
--name plundrio \
-p 9091:9091 \
-v /path/to/downloads:/downloads \
-e PLDR_TOKEN=your-token \
-e PLDR_TARGET=/downloads \
-e PLDR_FOLDER=plundrio \
ghcr.io/elsbrock/plundrio:latest
The Docker image is available for both x86_64 and ARM64 architectures. Docker will automatically pull the correct version for your platform.
Download the latest binary package for your platform (x86_64-linux or aarch64-linux) from the releases page. The multi-arch Docker image is available on GHCR (see Using Docker).
plundrio get-token
This will guide you through the OAuth authentication process and provide you with a token.
plundrio generate-config
This creates a template configuration file that you can customize.
Edit your configuration file or set environment variables to specify your download directory and put.io folder.
plundrio run \
--target /path/to/downloads \
--folder "plundrio" \
--token YOUR_PUTIO_TOKEN \
--workers 4
Add plundrio as a Transmission download client in your *arr application (see Configuring *arr Applications below).
plundrio supports multiple configuration methods:
target: /path/to/downloads # Target directory for downloads
folder: "plundrio" # Folder name on put.io
token: "" # Put.io OAuth token (prefer env var)
listen: ":9091" # Transmission RPC server address
workers: 4 # Number of download workers
log_level: "info" # Log level (trace,debug,info,warn,error,fatal,panic,none,pretty)
Command-line flags (see full list with plundrio run --help)
Environment variables (prefixed with PLDR_):
export PLDR_TARGET=/path/to/downloads
export PLDR_TOKEN=your-putio-token
export PLDR_FOLDER=plundrio
export PLDR_LISTEN=:9091
export PLDR_WORKERS=4
export PLDR_LOG_LEVEL=info
Configuration values are loaded in the following order, with later sources overriding earlier ones:
💡 Security Note: Store OAuth tokens in environment variables rather than config files or command-line arguments for better security.
To add plundrio to your *arr application (Sonarr, Radarr, etc.):
/transmission/plundrio will now automatically handle downloads from your *arr application through put.io.
plundrio run \
--target /path/to/downloads \
--folder "plundrio" \
--token YOUR_PUTIO_TOKEN \
--workers 4
plundrio generate-config
plundrio get-token
Trash Bin Management: We recommend turning off the trash bin in your put.io settings. This helps keep your put.io account clean and saves space. The trash cannot be deleted programmatically.
Download Speed Optimization: Downloads are optimized using the grab library for maximum efficiency. The default worker count of 4 allows for parallel downloads to maximize your available bandwidth.
Worker Count Tuning:
Monitor system resource usage to find the optimal setting for your environment
Automatic Downloads: If you set the default download folder of put.io to the folder configured in plundrio, you can automatically download files added through other means (e.g., via chill.institute).
Security Best Practices:
Verify the correct host/IP is configured in your *arr application
Authentication Failures
plundrio get-tokenCheck that the token is correctly set in your configuration
Download Issues
Ensure your put.io account is active and has the files available
Performance Problems
Can I use plundrio without *arr applications?
Yes, plundrio will monitor and download any transfers in your configured put.io folder, regardless of how they were added.
How does plundrio compare to the official put.io client?
plundrio focuses on automation and integration with *arr applications, while the official client offers a more general-purpose interface.
Can I run multiple instances of plundrio?
Yes, plundrio is stateless and can be run in multiple instances, even pointing to the same put.io account with different configurations.
Does plundrio support VPNs or proxies?
plundrio uses your system's network configuration. If your system routes through a VPN or proxy, plundrio will use that connection.
How can I monitor plundrio's status?
plundrio logs its activities to stdout. You can redirect these logs to a file or use a log management system.
Contributions to plundrio are welcome! Here's how you can contribute:
Submit a pull request
Bug Reports:
Provide system information
Feature Requests:
Explain the use case and benefits
Documentation:
Please open an issue first to discuss what you would like to change for major fe
$ claude mcp add plundrio \
-- python -m otcore.mcp_server <graph>