Rustatio Docs

🚀 Getting Started

Rustatio is available in three versions:

🖥️ Desktop App - Native application with full features, no CORS limitations
🐳 Docker - Self-hosted server version, accessible via web UI from any device
🌐 Web App - Browser-based version, works on any device, deployable to GitHub Pages

Desktop App Installation

Windows

Download the latest setup installer from Releases
Run the installer and follow the installation wizard
Launch Rustatio from the Start Menu

macOS

Download the latest Rustatio_*.dmg file from Releases
Open the downloaded file and drag Rustatio to your Applications folder
Launch Rustatio from Applications (you may need to allow it in System Preferences → Security & Privacy)

Linux

Download from Releases

Debian/Ubuntu:

sudo apt install ./Rustatio_*.deb

Fedora/RHEL/CentOS:

sudo dnf install Rustatio-*.rpm

AppImage (Universal):

chmod +x Rustatio_*.AppImage && ./Rustatio_*.AppImage

Docker (Self-Hosted)

Run Rustatio on your server, NAS, or any Docker-enabled system. The web UI is accessible from any device on your network.

Quick Start with Docker Compose

Create a docker-compose.yml file:

services:
  rustatio:
    image: ghcr.io/takitsu21/rustatio:latest
    container_name: rustatio
    ports:
      - "${WEBUI_PORT:-8080}:8080"  # Rustatio Web UI
    environment:
      - PORT=8080
      - RUST_LOG=${RUST_LOG:-info}
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      # Optional authentication for your server (Recommended if exposing on internet)
      # - AUTH_TOKEN=${AUTH_TOKEN:-CHANGE_ME}
    volumes:
      - rustatio_data:/data
      # Optional: Uncomment to enable watch folder feature
      # - ${TORRENTS_DIR:-./path/to/your/torrents}:/torrents
    restart: unless-stopped

volumes:
  rustatio_data:

Start the container:

docker compose up -d

Access the web UI at http://localhost:8080 (or your server's IP)

User/Group Permissions (PUID/PGID)

The container supports LinuxServer.io-style PUID/PGID environment variables to ensure correct file permissions on mounted volumes:

Variable	Description	Default
`PUID`	User ID the container runs as	`1000`
`PGID`	Group ID the container runs as	`1000`

Find your IDs: id -u && id -g

Authentication (AUTH_TOKEN)

When exposing Rustatio to the internet or untrusted networks, you should enable authentication to protect your instance:

Variable	Description	Default
`AUTH_TOKEN`	Secret token required to access the web UI and API	(none - auth disabled)

To enable authentication:

environment:
  - AUTH_TOKEN=your-secure-secret-token

When AUTH_TOKEN is set:

The web UI displays a login page requiring the token
All API endpoints require authentication via Authorization: Bearer <token> header
SSE (Server-Sent Events) endpoints accept the token via ?token= query parameter

Generate a secure token: openssl rand -hex 32

Watch Folder Feature

Automatically detect and load torrent files from a folder:

Important: Create the directory on your host before starting the container. If Docker creates it, it will be owned by root and the container won't be able to access it.

# 1. Create the directory first (with your user permissions)
mkdir -p /path/to/your/torrents

# 2. Then start the container with the volume mounted

If you see a permission warning in the logs, fix it with:

sudo chown -R $(id -u):$(id -g) ./torrents

Custom Port Configuration

To change the web UI port:

# Using docker run
docker run -d -p 3000:8080 --name rustatio ghcr.io/takitsu21/rustatio:latest

# Using docker compose - change the ports mapping
ports:
  - "3000:8080"

Running Behind a VPN (Recommended)

For privacy, route all tracker requests through a VPN using gluetun:

services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      # Configure your VPN provider - see https://github.com/qdm12/gluetun-wiki
      - VPN_SERVICE_PROVIDER=protonvpn  # or: mullvad, nordvpn, expressvpn, etc.
      - VPN_TYPE=wireguard              # or: openvpn
      - VPN_PORT_FORWARDING=on          # if you want to enable port forwarding
      # Provider-specific settings (example for ProtonVPN WireGuard)
      - WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
      - SERVER_COUNTRIES=${SERVER_COUNTRIES:-Switzerland}
      # Gluetun control server auth (v3.39.1+ defaults to private routes)
      # If you want to have your network status available you have to disable the gluetun auth
      # Since the control server is only reachable within the container network namespace it is safe
      - HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE={"auth":"none"}
    ports:
      - "${WEBUI_PORT:-8080}:8080" # Rustatio Web UI
    restart: unless-stopped

  rustatio:
    image: ghcr.io/takitsu21/rustatio:latest
    container_name: rustatio
    environment:
      - PORT=8080
      - RUST_LOG=${RUST_LOG:-trace}
      - VPN_PORT_SYNC=${VPN_PORT_SYNC:-on}
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      # Optional authentication for your server (Recommended if exposing on internet)
      # - AUTH_TOKEN=${AUTH_TOKEN:-CHANGE_ME}
    volumes:
      - rustatio_data:/data
      # Optional: Uncomment to enable watch folder feature
      # - ${TORRENTS_DIR:-/path/to/your/torrents}:/torrents
    restart: unless-stopped
    network_mode: service:gluetun
    depends_on:
      gluetun:
        condition: service_healthy

volumes:
  rustatio_data:

Note: The ports are defined on the gluetun container since Rustatio uses its network stack. See the gluetun wiki for VPN provider-specific configuration.

Dynamic forwarded port sync: When VPN_PORT_SYNC=on, new server instances can enable VPN sync in the UI so Rustatio follows Gluetun's current forwarded port automatically. Existing instances stay on their saved manual port unless you enable the toggle for that instance.

Requirements for VPN sync:

Gluetun port forwarding must be enabled with VPN_PORT_FORWARDING=on

Rustatio server-side sync must be enabled with VPN_PORT_SYNC=on

Gluetun must expose a real forwarded port (not 0) for your VPN provider/server

Running instances keep their current port until restart; new/stopped instances pick up the latest forwarded port automatically

If VPN sync is enabled in the UI but no forwarded port is available yet, Rustatio will warn you and keep waiting until Gluetun reports one.

Docker Features:

✅ No CORS limitations (server handles tracker requests)
✅ Runs on any Docker-enabled system (Linux, Windows, macOS, NAS)
✅ Multi-architecture support (amd64, arm64)
✅ PUID/PGID support for correct volume permissions
✅ Optional watch folder for automatic torrent loading

Web App Usage

Live Demo: https://takitsu21.github.io/rustatio/

The web version runs entirely in your browser using WebAssembly.

⚠️ CORS Setup Required: Most BitTorrent trackers don't allow browser requests. You'll need to set up a free CORS proxy (takes 5 minutes).

📖 Complete Setup Guide - Step-by-step instructions for setting up your free Cloudflare Workers CORS proxy

Features compared to Desktop:

✅ Same core functionality (ratio faking, client emulation)
✅ Works on any device with a modern browser
✅ No installation required
✅ Session persistence via localStorage
⚠️ Requires CORS proxy for most trackers

📖 Usage (Desktop & Web)

Select Torrent: Click "Select Torrent File" and choose your .torrent file
Configure Settings:
- Choose which client to emulate
- Set upload/download rates (KB/s)
- Set initial completion percentage
- Configure port and other options
Start Faking: Click "Start" to begin
Monitor Stats: Watch real-time statistics update every seconds
Stop: Click "Stop" when done

⚙️ Configuration

Configuration is automatically saved when using the UI. Settings are stored in:

Linux/macOS: ~/.config/rustatio/config.toml
Windows: %APPDATA%\rustatio\config.toml

You can also manually edit the configuration file. Example configuration:

[client]
default_type = "qbittorrent"
default_port = 6881
default_num_want = 50

[faker]
default_upload_rate = 50.0
default_download_rate = 100.0
default_announce_interval = 1800
update_interval = 5

[ui]
window_width = 1200
window_height = 800
dark_mode = true

🎯 Supported Clients

uTorrent (default: 3.5.5)
qBittorrent (default: 5.1.4)
Transmission (default: 4.0.5)
Deluge (default: 2.1.1)

Each client is accurately emulated with proper:

Peer ID format
User-Agent headers
HTTP protocol version
Query parameter ordering

🔧 How It Works

Torrent Parsing: Reads .torrent file and extracts info_hash and tracker URL
Client Spoofing: Generates authentic-looking peer ID and key for selected client
Tracker Announce: Sends periodic announces to tracker with fake stats
Stat Accumulation: Simulates upload/download based on configured rates
Real-time Updates: Updates statistics and re-announces at tracker-specified intervals

For Users:

📖 WEB_VERSION.md - How to use the web version and set up CORS proxy (5 minute guide)

Get Started