Local installation

Install TorBox Media Center directly on your system without Docker

You can run TorBox Media Center directly on your system using Python, without Docker. This method gives you more control but requires manual setup.

Prerequisites

• Python 3.6 or newer
• Git (optional, for cloning the repository)
• A TorBox account on a paid plan (sign up here)
• Your TorBox API key from settings
• Linux/Unix/BSD/MacOS for FUSE support (STRM works on all platforms including Windows)

Installation

1. Download the source code

   Clone the repository using Git:

   git clone https://github.com/TorBox-App/torbox-media-center.git
   cd torbox-media-center
   

   Or download the ZIP file from GitHub and extract it:

   unzip torbox-media-center-main.zip
   cd torbox-media-center-main
   
2. Create environment file

   Create a .env file for your configuration:

   cp .env.example .env
   

   Or create a new .env file manually:

   touch .env
   
3. Configure environment variables

   Edit the .env file and add your configuration:

   TORBOX_API_KEY=your_api_key_here
   MOUNT_METHOD=strm
   MOUNT_PATH=/home/yourusername/torbox
   MOUNT_REFRESH_TIME=normal
   ENABLE_METADATA=false
   RAW_MODE=false
   

   • Replace your_api_key_here with your actual API key from torbox.app/settings
   • Set MOUNT_PATH to an existing directory where you want your media accessible
   • Choose strm or fuse for MOUNT_METHOD
4. Install Python dependencies

   Install all required packages from requirements.txt:

   pip3 install -r requirements.txt
   

   This will install:

   • apscheduler - Task scheduling
   • tinydb - Lightweight database
   • httpx - HTTP client
   • python-dotenv - Environment variable management
   • parse-torrent-title - Media metadata parsing
   • fuse-python - FUSE filesystem support (Linux only)
   • GitPython - Git operations

   On Windows, FUSE support is not available. Use MOUNT_METHOD=strm instead.

   On macOS, FUSE requires macFUSE to be installed separately.

5. Create mount directory

   Ensure the mount path exists and is accessible:

   mkdir -p ~/torbox
   

   Make sure the user running the script has write permissions:

   chmod 755 ~/torbox
   
6. Run the application

   Start TorBox Media Center:

   python3 main.py
   

   The application will:

   • Validate your API key
   • Connect to TorBox services
   • Begin syncing your media files
   • Keep running in the foreground

   Keep the terminal window open. Closing it will stop the application.

Running in the background

To keep TorBox Media Center running after closing your terminal:

Using nohup

nohup python3 main.py &

Using screen

screen -S torbox
python3 main.py
# Press Ctrl+A then D to detach

Reattach with:

screen -r torbox

Using systemd (Linux)

Create a systemd service file:

/etc/systemd/system/torbox-media-center.service

[Unit]
Description=TorBox Media Center
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/path/to/torbox-media-center
ExecStart=/usr/bin/python3 /path/to/torbox-media-center/main.py
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable torbox-media-center
sudo systemctl start torbox-media-center

Check status:

sudo systemctl status torbox-media-center

Environment variables reference

Required:

• TORBOX_API_KEY - Your TorBox API key from torbox.app/settings

Optional:

• MOUNT_METHOD - Either strm or fuse (default: strm)
• MOUNT_PATH - Directory where media files will be accessible (must exist)
• MOUNT_REFRESH_TIME - Sync frequency: slowest, very_slow, slow, normal, fast, ultra_fast, or instant (default: normal)
• ENABLE_METADATA - Enable automatic organization into movies/series folders (default: false)
• RAW_MODE - Use original file structure without organization (default: false)

Updating

To update to the latest version:

1. Stop the application

   If running in the foreground, press Ctrl+C. If using systemd:

   sudo systemctl stop torbox-media-center
   
2. Pull latest changes

   git pull origin main
   

   Or download the latest ZIP and extract it.

3. Update dependencies

   pip3 install -r requirements.txt --upgrade
   
4. Restart the application

   python3 main.py
   

   Or if using systemd:

   sudo systemctl start torbox-media-center
   

Troubleshooting

Python version issues

Check your Python version:

python3 --version

If it’s below 3.6, upgrade Python or use pyenv to manage multiple versions.

Permission errors

Ensure the mount path exists and is writable:

mkdir -p ~/torbox
chmod 755 ~/torbox

FUSE errors on Linux

Install FUSE development libraries:

Ubuntu/Debian

sudo apt-get install libfuse-dev fuse

Fedora/CentOS

sudo dnf install fuse-devel fuse

Missing dependencies

If pip3 install fails, you may need development tools:

Ubuntu/Debian

sudo apt-get install python3-dev build-essential

macOS

xcode-select --install

Next steps

After installation:

1. Your media files will appear at the MOUNT_PATH you configured
2. Configure your media server to use:
   • Movies: <MOUNT_PATH>/movies
   • TV Shows: <MOUNT_PATH>/series
3. Check the application logs for any errors

See the Configuration guide for advanced settings and the Troubleshooting guide if you encounter issues.