Skip to main content
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: 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.