WebUI Overview¶

Torrentarr includes a modern, React-based web interface for real-time monitoring, configuration management, and system control. Built with TypeScript and Mantine UI components, the WebUI provides a responsive, intuitive interface for managing your Torrentarr instance.

Accessing the WebUI¶

Default URL¶

The WebUI is available at:

http://localhost:6969/ui

Or if you've changed the port in your configuration:

http://YOUR_SERVER_IP:YOUR_PORT/ui

Configuration¶

WebUI settings are configured in config.toml:

[WebUI]
# Bind address (0.0.0.0 for all interfaces, 127.0.0.1 for localhost only)
Host = "0.0.0.0"

# Port number
Port = 6969

# Optional authentication token
Token = ""

# WebUI-specific display settings
LiveArr = true        # Enable live Arr instance views
GroupSonarr = true    # Group Sonarr series by show
GroupLidarr = true    # Group Lidarr albums by artist
Theme = "Dark"        # Dark | Light | Auto

Remote Access¶

To access the WebUI remotely:

Option 1: Direct Access (Not Recommended for Public)

[WebUI]
Host = "0.0.0.0"  # Listen on all interfaces
Port = 6969
Token = "your-secure-random-token-here"  # Require authentication

Option 2: Reverse Proxy (Recommended)

Use Nginx, Caddy, or Traefik to proxy requests:

location /torrentarr/ {
    proxy_pass http://localhost:6969/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

torrentarr.example.com {
    reverse_proxy localhost:6969
}

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.torrentarr.rule=Host(`torrentarr.example.com`)"
  - "traefik.http.services.torrentarr.loadbalancer.server.port=6969"

Option 3: SSH Tunnel

# Forward remote port 6969 to local
ssh -L 6969:localhost:6969 user@your-server

# Access via http://localhost:6969/ui

Core Features¶

🔄 Process Management¶

Monitor and control all Torrentarr processes from a unified dashboard.

Features:

• Real-time Status - Live process state updates (Running, Stopped, Crashed)
• Health Indicators - Connection status to qBittorrent and Arr instances
• Process Control - Start, stop, or restart individual Arr manager processes
• Auto-restart Status - See if auto-restart is enabled and restart counts
• Process Logs - Quick access to process-specific logs

Use Cases:

• Restart a specific Arr instance without restarting Torrentarr
• Check if an Arr instance is properly connected
• Monitor which processes are consuming resources
• Verify auto-restart is working after failures

Detailed Process Management Guide →

📋 Live Log Viewer¶

Tail and search logs in real-time directly from your browser.

Features:

• Multiple Log Sources
• Main.log - Torrentarr core application logs
• WebUI.log - Web interface and API logs

• Per-Arr logs - Radarr-Movies.log, Sonarr-TV.log, etc.

• Advanced Filtering

• By log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• By search term (regex supported)
• By time range

• By source/category

• Real-time Updates - Auto-scroll and live updates via HTTP polling (1 second interval)

• Export - Download logs as text files
• Syntax Highlighting - Color-coded log levels
• Pagination - Load more logs on demand

Keyboard Shortcuts:

• Ctrl+F - Focus search box
• Esc - Clear search
• Space - Pause/resume auto-scroll

Use Cases:

• Debug torrent processing issues in real-time
• Monitor search activity across all Arr instances
• Track down errors without SSH access
• Share log excerpts with support

Detailed Log Viewer Guide →

🎬 Arr Instance Views¶

Browse and manage your media libraries directly from Torrentarr.

Radarr View¶

Features:

• Movie Library Table
• Title, year, quality profile, monitored status
• File information (size, codec, resolution)
• Custom format scores
• Download status (queued, downloading, imported)

• Missing vs. downloaded indicators

• Sorting & Filtering

• Sort by title, year, date added, quality, file size
• Filter by monitored status
• Filter by quality profile
• Filter by custom format score

• Search by title

• Quick Actions

• Trigger manual search
• Toggle monitoring
• View in Radarr (direct link)
• Refresh metadata

Statistics:

• Total movies: X
• Monitored: X
• Missing: X
• Downloaded: X
• Disk space used: X GB

Detailed Radarr View Guide →

Sonarr View¶

Features:

• Series Library Table
• Show title, seasons, episodes
• Monitored status per series/season
• Episode file information
• Next airing episode

• Download progress

• Grouping

• Group episodes by series (default)
• Flat view (all episodes)

• Group by season

• Episode Filtering

• Missing episodes
• Unmonitored episodes
• Aired vs. future episodes

• Episode quality

• Quick Actions

• Search for missing episodes
• Search for entire series
• Toggle series monitoring
• View in Sonarr

Statistics:

• Total series: X
• Monitored: X
• Episodes missing: X
• Episodes downloaded: X
• Next airing: [Show Name] - S01E05

Detailed Sonarr View Guide →

Lidarr View¶

Features:

• Album Library Table
• Artist, album title, release year
• Monitored status
• Track count and duration
• Quality (FLAC, MP3, etc.)

• Download status

• Grouping

• Group albums by artist (default)

• Flat view (all albums)

• Filtering

• By artist
• By quality
• By monitored status

• Missing vs. downloaded

• Quick Actions

• Search for missing albums
• Search for artist discography
• Toggle monitoring
• View in Lidarr

Statistics:

• Total artists: X
• Total albums: X
• Monitored albums: X
• Missing albums: X
• Disk space used: X GB

Detailed Lidarr View Guide →

📦 qBittorrent Categories¶

View and monitor all qBittorrent categories — both qBit-managed and Arr-managed — from a unified dashboard.

Features:

• Category Overview
• Total category count across all qBittorrent instances
• Breakdown of qBit-managed vs. Arr-managed categories

• Aggregate torrent count, seeding count, and total size

• Category Table

• Category name
• Managed By indicator (qBit or Arr badge)
• Instance name (for multi-instance setups)
• Torrent count and seeding count
• Total size
• Average ratio and average seeding time
• Configured max ratio and max seeding time

• Removal mode (Never, On Ratio, On Time, Ratio OR Time, Ratio AND Time)

• Live Updates

• Auto-refresh every 1 second when "Live Arr" is enabled
• Auto-refresh every 30 seconds otherwise
• Manual refresh button

Use Cases:

• Monitor seeding progress across manually added torrents
• Verify that seeding limits are correctly applied
• Track category usage across multiple qBittorrent instances
• Confirm that qBit-managed and Arr-managed categories don't overlap

For configuration details, see Managed Categories & Seeding Settings.

⚙️ Configuration Editor¶

Edit your Torrentarr configuration without leaving the browser.

Features:

• Form-Based Editor
• Structured configuration editing
• Organized by section (Settings, WebUI, qBit, Arr instances)

• Helpful descriptions for each option

• Validation

• Real-time syntax validation
• Error highlighting with line numbers
• Helpful error messages

• Schema validation

• Configuration Testing

• Test connection to qBittorrent
• Test connection to Arr instances
• Validate API keys

• Check path accessibility

• Backup & Restore

• Automatic backup before saving
• Manual backup creation
• Restore from previous backups

• Download configuration file

• Apply Changes

• Save configuration
• Restart Torrentarr with new config
• Restart specific Arr instances only
• Rollback on failure

Safety Features:

• ✅ Validation before saving
• ✅ Automatic backup creation
• ✅ Rollback on invalid config
• ✅ Confirmation dialogs for destructive actions

Use Cases:

• Adjust settings without SSH/terminal access
• Test configuration changes safely
• Quick fixes without text editor
• Manage Torrentarr from mobile devices

Detailed Configuration Editor Guide →

📊 System Dashboard¶

Overview of Torrentarr's health and performance.

Metrics Displayed:

• Version Information
• Torrentarr version
• .NET runtime version
• qBittorrent version

• Arr instance versions

• Uptime & Performance

• Torrentarr uptime
• Total torrents processed
• Successful imports
• Failed downloads handled

• Average processing time

• Storage & Resources

• Disk space on download folder
• Database size
• Log file sizes

• Memory usage (if available)

• Connection Status

• qBittorrent: ✅ Connected / ❌ Disconnected
• Radarr instances: ✅/❌
• Sonarr instances: ✅/❌
• Lidarr instances: ✅/❌

• Overseerr/Ombi: ✅/❌

• Recent Activity

• Last 10 imports
• Last 5 searches triggered
• Recent errors
• Latest processed torrents

Refresh Rates:

• Connection status: Every 30 seconds
• Metrics: Every 60 seconds
• Activity: Real-time (1-second polling)

Navigation & Interface¶

Main Navigation¶

The WebUI uses a tab-based navigation system:

Header Bar¶

• Logo & Title - Click to return to Processes tab
• Theme Toggle - Switch between Dark/Light/Auto
• Refresh Indicator - Shows when data is being fetched
• Connection Status - Icon indicates connection to backend
• Version Badge - Current Torrentarr version

Footer Bar¶

• Status Messages - Success/error notifications
• Active Processes - Count of running Arr instances
• Last Update - Timestamp of last data refresh

Authentication & Security¶

Token-Based Authentication¶

Protect your WebUI with token authentication:

[WebUI]
Token = "your-secure-random-token-here"

Generate a secure token:

# Using openssl
openssl rand -base64 32

# Using Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Using the token:

When configured, all API requests require the Authorization: Bearer header:

curl http://localhost:6969/api/processes \
  -H "Authorization: Bearer your-token-here"

The WebUI automatically includes the token if you access it through the main interface.

Network Security¶

Localhost Only (Recommended for Local Use):

[WebUI]
Host = "127.0.0.1"  # Only accessible from localhost
Port = 6969
Token = ""  # Optional for localhost

All Interfaces (Requires Token):

[WebUI]
Host = "0.0.0.0"  # Accessible from network
Port = 6969
Token = "your-secure-token"  # REQUIRED for security

Best Practices:

• ✅ Always use HTTPS via reverse proxy for internet access
• ✅ Set a strong token if binding to 0.0.0.0
• ✅ Use firewall rules to restrict access
• ✅ Consider VPN access for remote management
• ❌ Never expose without authentication to the internet

Themes & Appearance¶

Theme Options¶

The WebUI supports three theme modes:

Dark Mode (Default)

• Easy on the eyes for extended monitoring
• Reduced eye strain in low-light environments
• Better for OLED displays

Light Mode

• High contrast for bright environments
• Traditional appearance
• Better for daytime use

Auto Mode

• Follows system/browser preference
• Automatically switches based on time of day (if system supports)
• Best for users who toggle system themes

Customization¶

Theme preference is stored in browser local storage and persists across sessions.

Manual Theme Toggle:

Click the sun/moon icon in the top-right corner of the navigation bar.

Keyboard Shortcut:

• Ctrl+Shift+T - Toggle theme

Performance & Optimization¶

Data Refresh Rates¶

Different components refresh at different intervals:

Performance Tips¶

For Large Libraries (1000+ items):

• Enable pagination in table settings
• Use search/filter instead of scrolling
• Limit log entries shown (default: 100)

For Slow Connections:

• Disable auto-refresh temporarily
• Reduce page size in tables
• Use search to find specific items

For Low-Resource Systems:

• Close unused tabs
• Limit concurrent log streams
• Disable live updates when not needed

Mobile & Tablet Support¶

The WebUI is fully responsive and optimized for all screen sizes.

Desktop (1200px+)¶

• Full-width tables with all columns
• Side-by-side layouts
• Keyboard shortcuts enabled
• Multi-column forms

Tablet (768px - 1199px)¶

• Adjusted table column widths
• Collapsible sidebars
• Touch-optimized controls
• Two-column forms

Mobile (< 768px)¶

• Single-column layouts
• Hamburger menu navigation
• Card-based views (alternative to tables)
• Swipe gestures for navigation
• Bottom navigation bar

Touch Gestures¶

• Swipe Left/Right - Navigate between tabs
• Pull to Refresh - Refresh current view
• Long Press - Show context menu
• Pinch to Zoom - Zoom tables (where applicable)

Keyboard Shortcuts¶

Note: Keyboard navigation is fully supported (Tab, Shift+Tab, Enter, Arrow keys).

API Integration¶

The WebUI is built on Torrentarr's REST API. All functionality is accessible programmatically.

Base URL¶

http://localhost:6969/api

Common Endpoints¶

GET  /api/processes           # List all processes
POST /api/processes/:name/restart  # Restart process
GET  /api/logs                # Get logs
GET  /api/radarr/movies       # List Radarr movies
GET  /api/sonarr/series       # List Sonarr series
GET  /api/lidarr/albums       # List Lidarr albums
GET  /api/config              # Get configuration
POST /api/config              # Update configuration
GET  /api/health              # Health check

Authentication¶

Include the token in the Authorization header:

curl http://localhost:6969/api/processes \
  -H "Authorization: Bearer your-token"

Response Format¶

All responses are JSON:

{
  "success": true,
  "data": { ... },
  "error": null,
  "timestamp": "2025-12-08T12:00:00Z"
}

Full API Reference →

Troubleshooting¶

WebUI Not Loading¶

Symptoms: Can't access WebUI at http://localhost:6969/ui

Solutions:

1. Check Torrentarr is running:

   DockerSystemdNative (dotnet/binary)

   docker ps | grep torrentarr
   # If not running:
   docker-compose up -d torrentarr
   

   systemctl status torrentarr
   # If not running:
   sudo systemctl start torrentarr
   

   ps aux | grep -E "Torrentarr|dotnet"
   # If not running:
   dotnet run --project src/Torrentarr.Host/Torrentarr.Host.csproj
   # Or run the installed binary / dotnet tool
   

2. Verify port configuration:

   [WebUI]
   Port = 6969  # Check your config.toml
   Host = "0.0.0.0"  # Or "127.0.0.1"
   

3. Check port mapping (Docker):

   docker run -p 6969:6969 ...
   # Ensure host port matches container port
   

4. Test port accessibility:

   # From server
   curl http://localhost:6969/api/health
   
   # From remote machine
   curl http://SERVER_IP:6969/api/health
   

5. Check firewall rules:

   # Ubuntu/Debian
   sudo ufw allow 6969
   sudo ufw status
   
   # CentOS/RHEL
   sudo firewall-cmd --add-port=6969/tcp --permanent
   sudo firewall-cmd --reload
   

6. Check logs for errors:

   # Docker
   docker logs torrentarr | grep -i webui
   
   # Native
   tail -f ~/config/logs/WebUI.log
   

Authentication Errors¶

Symptoms: API requests return 401 Unauthorized

Solutions:

1. Check if token is configured:

   [WebUI]
   Token = "your-token-here"  # If set, token is required
   

2. Verify token in requests:

   # Correct
   curl http://localhost:6969/api/processes \
     -H "Authorization: Bearer your-token-here"
   
   # Incorrect (missing header)
   curl http://localhost:6969/api/processes
   

3. Check token hasn't changed:

   • If you updated the token in config, restart Torrentarr
   • Clear browser cache/cookies
   • Re-access the WebUI

4. Test without token:

   Temporarily disable token to test:

   [WebUI]
   Token = ""  # Empty = no authentication
   

   Restart Torrentarr and test. Re-enable token afterward.

Blank Page / White Screen¶

Symptoms: WebUI loads but shows blank/white page

Solutions:

1. Clear browser cache:

   • Ctrl+Shift+Del → Clear cache and reload
   • Or try incognito/private mode

2. Check browser console for errors:

   • Open Developer Tools (F12)
   • Go to Console tab
   • Look for JavaScript errors

3. Verify WebUI files exist:

   # Check static files
   ls -la /path/to/Torrentarr/static/
   # Should contain index.html, assets/, etc.
   

4. Try a different browser:

   • Supported: Chrome, Firefox, Edge, Safari (latest versions)
   • Unsupported: IE11 and older

5. Check for reverse proxy issues:

   If using Nginx/Caddy/Traefik, verify: - WebSocket support is enabled - Headers are properly forwarded - No URL rewriting conflicts

Slow Performance / Lag¶

Symptoms: WebUI is slow, unresponsive, or freezes

Solutions:

1. Reduce data load:

   • Logs tab: Limit to 50-100 entries
   • Arr views: Use search/filter instead of loading all
   • Disable auto-refresh: Manually refresh when needed

2. Check system resources:

   # Docker
   docker stats torrentarr
   
   # Native
   htop
   top -p $(pidof torrentarr)
   

3. Browser performance:

   • Close unused tabs
   • Disable browser extensions
   • Update to latest browser version
   • Check for high CPU/memory usage

4. Network latency:

   # Test API response time
   time curl http://localhost:6969/api/health
   

5. Database size:

   # Check database size
   ls -lh ~/config/torrentarr.db
   
   # If large, consider VACUUM (stop Torrentarr first)
   sqlite3 ~/config/torrentarr.db "VACUUM;"
   

Real-Time Updates Not Working¶

Symptoms: Logs/data don't update automatically

Solutions:

1. Check polling is active:

   • Open browser Developer Tools (F12)
   • Go to Network tab
   • Filter by "Fetch/XHR"
   • Should see periodic requests to /api/processes every 1 second

2. Verify browser settings:

   • Ensure JavaScript is enabled
   • Check browser isn't throttling background tabs
   • Disable power saving modes that may affect tab activity

3. Manual refresh as fallback:

   • Click refresh button to manually update
   • Or reload the page (Ctrl+R)

Config Editor Not Saving¶

Symptoms: Changes to config.toml don't persist

Solutions:

1. Check file permissions:

   # Ensure Torrentarr can write to config
   ls -la ~/config/config.toml
   chmod 644 ~/config/config.toml
   

2. Verify config syntax:

   • Use the built-in validator before saving
   • Look for TOML syntax errors (quotes, brackets, etc.)

3. Check disk space:

   df -h /path/to/config
   # Ensure sufficient free space
   

4. Review logs:

   tail -f ~/config/logs/WebUI.log
   # Look for permission denied or write errors
   

5. Restart required:

   • Some changes require Torrentarr restart
   • Check if "Restart Required" message appears

Connection Status Shows Disconnected¶

Symptoms: Dashboard shows Arr instances as disconnected despite working

Solutions:

1. Test connections manually:

   # Test Radarr
   curl -H "X-Api-Key: YOUR_KEY" http://localhost:7878/api/v3/system/status
   
   # Test Sonarr
   curl -H "X-Api-Key: YOUR_KEY" http://localhost:8989/api/v3/system/status
   

2. Check API keys:

   • Verify API keys are correct in config
   • Ensure no extra spaces or quotes

3. Verify URIs:

   [Radarr-Movies]
   URI = "http://localhost:7878"  # Correct
   # NOT: "http://localhost:7878/" (trailing slash)
   # NOT: "localhost:7878" (missing protocol)
   

4. Check network connectivity:

   • Ensure Torrentarr can reach Arr instances
   • Check Docker network (if using containers)

5. Review Arr logs:

   • Check Arr instances are running
   • Look for rate limiting or authentication errors

Data Not Updating¶

Symptoms: Movie/series lists show outdated information

Solutions:

1. Force refresh:

   • Click refresh button in the WebUI
   • Or reload the page (Ctrl+R)

2. Check cache settings:

   • WebUI caches data for 30 seconds by default
   • Wait 30s and refresh

3. Verify Arr instances are syncing:

   • Check Arr instance logs
   • Ensure Arr has indexers configured

4. Clear browser cache:

   • Ctrl+Shift+Del
   • Select "Cached images and files"

Mobile Display Issues¶

Symptoms: WebUI looks broken or unresponsive on mobile

Solutions:

1. Update to latest version:

   • Mobile support improved in recent versions
   • Update Torrentarr to latest release

2. Try landscape mode:

   • Some views work better in landscape

3. Use desktop site mode:

   • In mobile browser, enable "Desktop site"
   • Better for tablets

4. Check screen size:

   • Minimum supported width: 320px
   • Some features hidden on very small screens

5. Report layout issues:

   • Include device model and browser version
   • Screenshot of the issue

Browser Compatibility¶

Supported Browsers¶

Unsupported Browsers¶

• ❌ Internet Explorer (all versions)
• ❌ Legacy Edge (pre-Chromium)
• ⚠️ Older mobile browsers (Android < 7, iOS < 14)

Required Browser Features¶

• ES6 JavaScript support
• Periodic polling support (for real-time updates)
• LocalStorage (for preferences)
• Flexbox and CSS Grid
• SVG support

Advanced Usage¶

Custom Reverse Proxy Headers¶

When using a reverse proxy, configure these headers for optimal experience:

# Nginx example
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;

# WebSocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

CORS Configuration¶

If accessing WebUI from a different domain:

[WebUI]
# Allow specific origins (comma-separated)
CORSOrigins = "https://myapp.com,https://admin.myapp.com"

# Or allow all (not recommended for production)
CORSOrigins = "*"

Rate Limiting¶

Protect against abuse with built-in rate limiting:

[WebUI]
# Max requests per minute per IP
RateLimit = 60

# Burst allowance
RateLimitBurst = 10

Accessibility¶

Keyboard Navigation¶

The WebUI supports full keyboard navigation:

• Tab - Navigate between interactive elements
• Shift+Tab - Navigate backwards
• Enter - Activate buttons/links
• Space - Toggle checkboxes
• ++arrow-keys++ - Navigate within tables/lists
• Esc - Close modals/dialogs

Screen Reader Support¶

• ARIA labels on all interactive elements
• Semantic HTML structure
• Skip navigation links
• Alt text on images/icons
• Descriptive button labels

Visual Accessibility¶

• High contrast mode compatible
• Minimum 4.5:1 contrast ratio (WCAG AA)
• No color-only information
• Resizable text (up to 200%)
• Focus indicators on all interactive elements

Related Documentation¶

Configuration¶

• WebUI Configuration - Detailed WebUI settings
• Configuration File - Complete config reference
• Environment Variables - WebUI env vars

Features¶

• Process Management - Managing Arr processes
• Health Monitoring - Torrent health checks
• Automated Search - Search automation

Reference¶

• API Reference - Complete API documentation
• CLI Reference - Command-line options
• Glossary - Terms and definitions

Support¶

• Troubleshooting - General troubleshooting
• Common Issues - Known problems
• FAQ - Frequently asked questions

Getting Help¶

Community Support¶

• GitHub Discussions - Ask questions, share tips
• GitHub Issues - Report bugs, request features
• Discord - Real-time community chat

Bug Reports¶

When reporting WebUI issues, include:

1. Browser & Version - e.g., Chrome 120, Firefox 121
2. Operating System - e.g., Windows 11, macOS 14, Ubuntu 22.04
3. Torrentarr Version - Found in WebUI header
4. Console Errors - From browser Developer Tools (F12)
5. Steps to Reproduce - How to trigger the issue
6. Screenshots - Visual representation helps

Feature Requests¶

Have an idea for the WebUI? Open a discussion with:

• Use Case - Why is this feature needed?
• Proposed Solution - How should it work?
• Alternatives - Other ways to achieve the same goal