Skip to Content
Ombi

Ombi

Universal request management for Plex, Jellyfin, and Emby

Ombi is a self-hosted web application that provides a beautiful interface for managing content requests across Plex, Jellyfin, and Emby media servers. Users can browse, discover, and request movies, TV shows, and music through an intuitive web interface—Ombi then automatically forwards approved requests to Sonarr, Radarr, and Lidarr for download and processing. With user management, approval workflows, comprehensive notification support, and an automated invitation system, Ombi streamlines content management for shared media servers.

Multi-Server Support

Connect to Plex, Jellyfin, and Emby simultaneously—support for all three media server platforms

Media Management Integration

Automatic request forwarding to Sonarr, Radarr, Lidarr, CouchPotato, and SickChill

User Management

Roles, quotas, approval workflows, and automated invitation system for easy onboarding

Rich Notifications

Discord, Slack, email, Telegram, mobile push, and webhook notification support

Invitation System

Automated email invitations with automatic media server account creation

Customizable Interface

Themes, custom CSS, landing pages, and full branding customization options

Reverse Proxy Access

Secure nginx reverse proxy with user-scoped URL paths

Database Options

SQLite (default) or optional MySQL/MariaDB migration for enhanced performance

Multi-Server Flexibility
Note

Ombi is unique among request managers—it supports Plex, Jellyfin, and Emby simultaneously. You can connect all three servers at once or use it with a single media server of your choice.


Installation

Prerequisites

  • QuickBox Pro v3 installed and configured
  • Target QuickBox user already exists (qb user create)
  • Plex, Jellyfin, or Emby media server installed and running (at least one required)
  • Sonarr and/or Radarr configured with media libraries (recommended)

What you get

  • Per-user Ombi installation at /opt/username/Ombi with isolated configuration
  • Automatic download from GitHub beta releases for latest features
  • Reverse-proxied access at https://yourserver.com/username/ombi
  • API key automatically extracted and saved to /home/username/.config/Ombi/ombi_api.txt
  • Managed systemd service ombi@username with journalctl logs

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Ombi in the catalog (browse Media Requests or search), and click Install. The dashboard streams the install log live and Ombi appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the Ombi row in the App Dashboard.

In the install dialog you can pick the release channel — Beta (the default) or Stable — and an optional reverse-proxy domain. See Channels & Versions for how channels work.

What you see is gated by your account: admins manage any user’s apps; regular users manage their own. See App Management for the full flow.

QuickBox automatically creates the per-user installation, configures the ombi@username systemd service with auto-start, sets up the nginx reverse proxy with a user-scoped URL, and extracts the API key from the database to /home/username/.config/Ombi/ombi_api.txt for easy access.

Install from the CLI (automation)

The CLI runs the same scripts as the Dashboard and is suited to automation and scripting:

bash
qb help ombi
qb install ombi -u username            # Beta channel (default)
qb install ombi -u username --stable   # Stable channel
qb reinstall ombi -u username
qb update ombi -u username
qb remove ombi -u username

Full flag reference: CLI Reference.

Port and API key
Info

Ombi runs on an auto-assigned port (base 5000, incremented per user) — find it in the App Dashboard (the Ombi row) or at /etc/systemd/system/ombi@username.service. The API key is in the API & Secrets section of the Ombi row, and is also extracted to /home/username/.config/Ombi/ombi_api.txt during install.


Directory Layout

Path
Description
/home/username/.config/Ombi
Ombi.db
Main SQLite database (user data, requests, settings). Present on SQLite only
OmbiSettings.db
Settings database (configuration, API keys, notifications). Present on SQLite only
OmbiExternal.db
External service integration data. Present on SQLite only
ombi_api.txt
Auto-extracted API key for integrations
database.json
Database connection settings; appears after a move to MySQL
*.db.bak
Copies of the three SQLite files kept by a move to MySQL
Logs/
Application logs directory

Per-User Installation Architecture

QuickBox Pro uses per-user isolation for Ombi installations:

text
/opt/username/Ombi/          # Ombi binary and runtime files
/home/username/.config/Ombi/ # Configuration, databases, and logs

Benefits:

  • True Multi-User Support: Each user gets isolated Ombi instance with separate configuration
  • Independent Updates: Update one user’s instance without affecting others
  • Enhanced Security: User-owned files prevent unauthorized modifications
  • Service Isolation: systemd services run with user-specific permissions

Network & Access

Ombi runs on an auto-assigned port (default base port 5000, incremented per user) and is accessible through nginx reverse proxy:

https://yourserver.com/username/ombi
QuickBox Dashboard Integration
Tip

Ombi is automatically integrated into your QuickBox dashboard. Find it on the App Dashboard (the default control view), expand its row for port and status, and click Open to launch the web interface.

First-Time Setup:

  1. Open Ombi web interface at the URL above
  2. Sign in with your QuickBox account name (letters and digits only) and your QuickBox password; QuickBox already created Ombi’s first admin
  3. Connect to Plex, Jellyfin, or Emby media server
  4. Add Sonarr, Radarr, and Lidarr integrations
  5. Configure notification channels (Discord, email, mobile)
  6. Set up user management rules and quotas
  7. Customize interface with themes and branding

Managing requests from the dashboard

Once Ombi is installed, its requests appear on the dashboard’s Media Requests page alongside every other Ombi and Seerr instance on the server — with posters, titles, and cast. You can review, approve, and deny requests there without opening each Ombi install separately, and the page discovers your instance automatically, with no URL or API key to configure. Access to that page is granted through a role; having Ombi installed does not by itself provide it.

Ombi keeps your denial reasons
Tip

When you deny a request from the Media Requests page, Ombi records the reason you enter and shows it to the requester — Seerr does not store one. Ombi reports availability as either available or not, without the partial state Seerr tracks for a series that has only partly arrived. Request submission, quotas, notifications, and automation stay in Ombi itself — the dashboard page is a review-and-decide surface over what Ombi already holds. See Media Requests for the full reference.

The dashboard also keeps its own record of your fulfilled requests, so a title stays visible on its Previously requested shelf even after Ombi removes it. If you have enabled Ombi’s Auto Delete Available Requests option (Ombi’s Settings > General), requests Ombi purged before the dashboard first saw them cannot be recovered and show only as a count — turn that option off if you want Ombi to keep its full history. See What history can and cannot recover.

MySQL installs: a rotated API key needs a manual entry
Warning

If you migrated Ombi to MySQL/MariaDB and later rotate its API key from inside Ombi, the dashboard does not re-read it automatically — set the new key as a Manual override in the dashboard’s Media Requests settings. SQLite installs (the default) re-export the key on update and need no manual step.


Services

Ombi uses a templated systemd unit (ombi@.service) for per-user isolation:

bash
# Check service status
systemctl status ombi@username
 
# View live logs
journalctl -u ombi@username -f
 
# Restart service
systemctl restart ombi@username
 
# Enable auto-start on boot (already enabled by default)
systemctl enable ombi@username
 
# Stop service
systemctl stop ombi@username

Service Configuration

The systemd service is configured with:

Working Directory
/opt/username/Ombi/
Storage Path
/home/username/.config/Ombi/
Base URL
/username/ombi (for reverse proxy integration)
Host Binding
http://0.0.0.0:port  (port auto-assigned starting at 5000)
  • User/Group: Runs as specified username with appropriate permissions
  • Auto-Restart: Automatically restarts on failure with 5-second delay
  • Timeout: 30-second graceful shutdown timeout

Initial Configuration

1. Sign In as the Admin

QuickBox creates Ombi’s first admin during install, so nobody else can claim the setup wizard. On first access to the Ombi web interface:

  1. Navigate to https://yourserver.com/username/ombi
  2. Sign in with your QuickBox account name and your QuickBox password. Ombi accepts only letters and digits in a login name, so any other character is left out (sent_s2 becomes sents2)
  3. Add further users from Ombi’s user management when you need them

2. Connect Media Server

Configure your media server integration (Settings → Media Server):

Plex Configuration:

  1. Select Plex tab
  2. Enter server details:
    • Server Name - Friendly name for your server
    • Hostname or IP - Server address (e.g., localhost or plex.domain.com)
    • Port - Plex port (default 32400)
    • Machine Identifier - Found in Plex server settings
    • Plex Auth Token - Obtain from https://www.plex.tv/claim  or Plex Web inspector
  3. Click Test Connectivity
  4. Click Save once verified
  5. Click Load Libraries to import media libraries

Jellyfin Configuration:

  1. Select Jellyfin tab
  2. Enter server details:
    • Server Name - Friendly name
    • Hostname or IP - Server address (e.g., localhost)
    • Port - Jellyfin port (default 8096)
    • API Key - From Jellyfin → Dashboard → API Keys
    • Administrator Username - Your Jellyfin admin username
  3. Click Test Connectivity, then Save
  4. Click Load Libraries

Emby Configuration:

  1. Select Emby tab
  2. Enter server details:
    • Server Name - Friendly name
    • Hostname or IP - Server address
    • Port - Emby port (default 8096)
    • API Key - From Emby → Dashboard → Advanced → API Keys
  3. Click Test Connectivity, then Save
  4. Click Load Libraries

3. Configure Media Management Integrations

Sonarr Configuration (TV Shows):

Navigate to Settings → TV → Sonarr:

  1. Enabled - Check to enable integration
  2. Default Server - Check if primary Sonarr instance
  3. Server Name - Descriptive name for this instance
  4. Hostname or IP - localhost (for local installations)
  5. Port - Your Sonarr port (default 8989)
  6. API Key - Copy from Sonarr’s row on the App Dashboard (API & Secrets section), or from Sonarr → Settings → General → API Key
  7. SSL - Uncheck (reverse proxy handles SSL)
  8. Quality Profile - Select default profile for TV shows
  9. Root Path - Select TV shows directory
  10. Language Profile - Select language preference
  11. Click Test to verify connection
  12. Click Save

Radarr Configuration (Movies):

Navigate to Settings → Movies → Radarr:

  1. Follow same configuration pattern as Sonarr
  2. Port - Your Radarr port (default 7878)
  3. API Key - From Radarr’s row on the App Dashboard (API & Secrets section), or Radarr → Settings → General → API Key
  4. Quality Profile - Select default movie quality profile
  5. Root Path - Select movies directory
  6. Minimum Availability - Select availability preference (Announced, In Cinemas, Released, etc.)
  7. Click Test, then Save

Lidarr Configuration (Music - Optional):

Navigate to Settings → Music → Lidarr:

  1. Follow same configuration pattern
  2. Port - Your Lidarr port (default 8686)
  3. API Key - From Lidarr’s row on the App Dashboard (API & Secrets section), or Lidarr → Settings → General
  4. Quality Profile - Select music quality profile
  5. Root Path - Select music directory
  6. Click Test, then Save

Common Tasks

Start, Stop, and Restart

bash
# Start Ombi
systemctl start ombi@username
 
# Stop Ombi
systemctl stop ombi@username
 
# Restart Ombi
systemctl restart ombi@username

Update Ombi

Update to the latest GitHub beta release:

bash
qb update ombi -u username

QuickBox automatically:

  • Stops the Ombi service
  • Backs up existing installation
  • Downloads latest beta release
  • Replaces binary files
  • Preserves configuration and databases
  • Restarts service

Reinstall Ombi

Reinstall while preserving configuration:

bash
qb reinstall ombi -u username

Use Cases:

  • Fix corrupted installation
  • Reset to clean state while keeping databases
  • Repair systemd service configuration
  • Regenerate nginx reverse proxy settings

Back up and restore

QuickBox backs Ombi up for you from the dashboard or the CLI, and the app keeps running while it does. Every backup is saved to /home/username/.QuickBox/software/ombi/backup/, named with the version and the date.

BackupWhat it saves
Config OnlyOmbiSettings.db, the settings database (configuration, API keys, notifications). Your users and requests are in Ombi.db, so use Full Backup for them
Full BackupTwo archives: ombi-<version>-config_<date>.tar.gz holds your config folder /home/username/.config/Ombi/ (the SQLite databases Ombi.db, OmbiSettings.db and OmbiExternal.db, taken as consistent copies, plus the other files in the folder), and ombi-<version>-application_<date>.tar.gz holds the install tree /opt/username/Ombi/
NginxOmbi’s nginx config, username.ombi.conf

A Full Backup holds the SQLite files only. If you moved Ombi to MySQL or MariaDB, your data is in that database and a Full Backup does not include it.

From the dashboard: to back up, open the App Dashboard, stay on Application Control, expand the Ombi row (click the row, or the arrow beside the app name, to open its options), open Operations, click Backup, then pick Full backup. Backup also offers Config Only and Nginx Only. You can instead open Content → Asset Management Center (AMC in the sidebar), choose the Application Backups tab, expand the Ombi row and click Back up now; that row lists every saved file with download and delete buttons. See App Management → Application Backups for who can see the tab.

To roll back from the dashboard: expand the Ombi row on the App Dashboard, open Operations, click Restore, pick the backup, then click Rollback. For a Full Backup the window offers Rollback, which puts back both the install tree and the config archive. Restore appears only when your account is allowed to restore backups.

From the CLI:

bash
# Config Only: OmbiSettings.db
qb manage software -o backup -u username -s ombi
 
# Full Backup: config folder with the databases, plus the install tree
qb manage software -o backup -o app -u username -s ombi
 
# Roll back to a Full Backup: pick the version from a menu, then confirm
qb manage software -o rollback -o app -u username -s ombi

Every option is described in the qb manage reference.

A rollback stops Ombi, clears the stale -wal, -shm and -journal files beside each restored database, puts the archives back, and starts Ombi again. If Ombi was answering on its port before the rollback, the command waits for it to answer again and reports an error instead of finishing quietly if it does not come back.

Remove deletes your backups
Caution

qb remove ombi deletes /home/username/.config/Ombi/ (the databases and settings) and the backup folder /home/username/.QuickBox/software/ombi/ with every backup in it, and clears the rollback list. qb reinstall ombi keeps your databases, settings and backups. Before a remove, download the Full Backup from the Application Backups tab in the Asset Management Center, or copy the folder somewhere QuickBox does not manage:

bash
cp -a /home/username/.QuickBox/software/ombi/backup /home/username/ombi-backup-saved

Remove Ombi

Complete removal with cleanup:

bash
qb remove ombi -u username

This removes:

  • Ombi binary and runtime files
  • Configuration directory and databases
  • systemd service file
  • nginx reverse proxy configuration
  • QuickBox database entries
  • Backup files
Data Loss Warning
Warning

Removing Ombi will permanently delete all configuration, user data, request history, and databases. Take a Full Backup and download it before removal, because remove also deletes the backup folder. The dashboard steps are in Back up and restore.

If you moved Ombi to MySQL/MariaDB, removal also cleans up on the MariaDB side:

  • It drops Ombi’s own database and database account, then deletes the account’s credentials file (/root/.my.username-ombi.cnf). It touches nothing in MariaDB for an Ombi that never moved, because that file is what marks the database as one QuickBox created.
  • It leaves the database and the account alone if MariaDB is not running at the time.
  • It keeps the MariaDB server itself when anything else still uses it: phpMyAdmin, another Ombi account, or any other database or database account. It removes the server only when Ombi installed it and nothing else uses it.
  • A database that another Ombi account still uses (older installs shared one) is dropped together with the last account that uses it.

Migrate to MySQL/MariaDB

Ombi uses SQLite by default, but you can move it to MySQL/MariaDB for better performance on high-traffic instances. The --ombi2mysql flag works with install, reinstall and update:

bash
# Move an existing Ombi
qb update ombi -u username --ombi2mysql
 
# Install a new Ombi straight onto MySQL
qb install ombi -u username --ombi2mysql
 
# Reinstall Ombi and move it in the same run
qb reinstall ombi -u username --ombi2mysql

If the account’s Ombi already uses MySQL, the move reports that and changes nothing, so the same command is safe to repeat. Ombi is moved only when you pass the flag.

Migration Process:

  1. Installs the MariaDB server and client from MariaDB’s package repository if the server is not already installed, then starts it
  2. Creates a dedicated database (ombi_username by default) and a dedicated database account, and saves the account’s credentials in /root/.my.username-ombi.cnf, readable by root only. It stops with an error if a database or account with those names already exists and was not created by QuickBox, so it never reuses yours
  3. Installs the Python modules the migration tool needs from your distribution’s packages
  4. Stops Ombi and keeps .bak copies of Ombi.db, OmbiSettings.db, OmbiExternal.db and any existing database.json
  5. Writes database.json so Ombi points at MySQL
  6. Creates the MySQL schema using Ombi itself
  7. Copies your data from SQLite into MySQL
  8. Removes the live SQLite .db files (the .bak copies stay in the config directory) and starts Ombi on the MySQL backend

If any step from the backup onward fails, QuickBox puts the .bak files back, removes the new database.json, and restarts Ombi on SQLite. The MariaDB database it created is left in place.

Options:

FlagEffect
--mysql-db=<database>Database name to create (default ombi_username)
--mysql-host=<host>MySQL host Ombi connects to (default localhost)
--mysql-port=<port>MySQL port Ombi connects to (default 3306)
--phpmyadminInstall phpMyAdmin for the new database after the move

Optional: Install phpMyAdmin

Add --phpmyadmin to install phpMyAdmin alongside the move:

bash
qb update ombi -u username --ombi2mysql --phpmyadmin

phpMyAdmin is installed for the first admin account and signs in with Ombi’s database account. It runs only when a move actually happens, not when Ombi is already on MySQL.

MySQL Performance Benefits
Info

MySQL/MariaDB provides better performance for Ombi installations with:

  • • Large user bases (50+ users)
  • • High request volume (hundreds of requests per day)
  • • Multiple concurrent users
  • • Complex approval workflows

For small personal servers with 5-10 users, SQLite is sufficient.


FAQ


Best Practices

Do

  • Set up Discord or email notifications for request updates and user activity monitoring
  • Configure user quotas to prevent request spam (5-10 requests per week recommended for regular users)
  • Enable approval workflows for non-admin users to moderate content before processing
  • Use Ombi's built-in invitation system for easy user onboarding with automatic account creation
  • Take a Full Backup before updates and reinstalls, and download a copy from the Application Backups tab in the Asset Management Center (Back up and restore)
  • Create custom user roles with granular permissions for different user tiers (VIP, regular, limited)
  • Enable mobile notifications (Pushbullet, Pushover) for on-the-go request management
  • Customize landing page and themes to match your server branding and create cohesive experience

Don't

  • Don't grant admin access to all users—use roles and quotas for proper access control
  • Don't disable approval workflows without quota limits—leads to request spam and storage issues
  • Don't manually edit Ombi databases while service is running—causes database corruption
  • Don't configure multiple default servers for same media type—creates conflicts and duplicate requests
  • Don't ignore failed notification configurations—check SMTP settings and webhook endpoints
  • Don't set unlimited quotas for all users—overwhelms storage capacity and bandwidth
  • Don't forget to configure root folders in Sonarr/Radarr—requests will fail without valid paths
  • Don't share admin credentials with users—use invitation system to create proper user accounts

Troubleshooting

Ombi Won’t Start

Symptoms:

  • Service fails immediately after start
  • Unable to access Ombi web interface
  • systemd service shows failed status

Resolution Steps:

bash
# Check service status and recent logs
systemctl status ombi@username
journalctl -u ombi@username -n 50
 
# Verify Ombi binary permissions
ls -la /opt/username/Ombi/Ombi
# Should show: -rwxr-xr-x (executable)
 
# Fix permissions if needed
chmod +x /opt/username/Ombi/Ombi
chown username:username /opt/username/Ombi/Ombi
 
# Restart service
systemctl restart ombi@username
Common Causes
Info

Binary permission issues typically occur after manual file operations or updates. QuickBox’s update command handles permissions automatically.

Cannot Connect to Media Server

Symptoms:

  • Plex/Jellyfin/Emby connection test fails
  • Error: “Unable to connect to server”
  • Libraries not loading after connection
  • Authentication errors with API key or token

Resolution Steps:

  1. Verify media server is running:

    bash
    # Check Plex status
    systemctl status plexmediaserver
     
    # Check Jellyfin status
    systemctl status jellyfin@username
     
    # Check Emby status
    systemctl status emby-server@username
  2. Verify hostname and port settings:

    • Use localhost for local servers (not 127.0.0.1 or server IP)
    • Confirm port matches media server configuration
    • Check firewall rules if using remote server
  3. Verify authentication credentials:

    • Plex: Auth token may have expired—generate new token from https://www.plex.tv/claim 
    • Jellyfin/Emby: API key must have admin permissions—regenerate if needed
  4. Test nginx reverse proxy:

    bash
    sudo nginx -t
    sudo systemctl reload nginx

Sonarr/Radarr Connection Failed

Symptoms:

  • Connection test fails in Ombi settings
  • Requests not forwarding to download clients
  • API authentication errors

Resolution Steps:

bash
# Verify services are running
systemctl status sonarr@username
systemctl status radarr@username
 
# Test API connectivity directly
curl http://localhost:7878/api/v3/system/status?apikey=YOUR_RADARR_API_KEY
curl http://localhost:8989/api/v3/system/status?apikey=YOUR_SONARR_API_KEY
 
# Check API keys match
# Radarr: Settings → General → Security → API Key
# Sonarr: Settings → General → Security → API Key

Configuration Checklist:

  • Yes Use localhost as hostname (not 127.0.0.1 or server IP)
  • Yes Port matches service port (7878 for Radarr, 8989 for Sonarr)
  • Yes SSL disabled in Ombi (reverse proxy handles encryption)
  • Yes Default Server checkbox enabled
  • Yes Quality profile selected
  • Yes Root path is valid and accessible

Requests Not Sending to Sonarr/Radarr

Symptoms:

  • Users can request content but nothing happens
  • No errors shown in Ombi interface
  • Requests remain in pending state

Resolution Steps:

bash
# Check Ombi logs for errors
journalctl -u ombi@username -f | grep -i error
 
# Common issues to verify:
# 1. Default server checkbox
#    Settings → Movies/TV → Check 'Default Server'
 
# 2. Quality profiles exist and are valid
#    Verify profile name matches Sonarr/Radarr configuration
 
# 3. Root paths are configured and accessible
#    Test path write permissions: touch /path/to/media/test.txt
 
# 4. Test manual request from Ombi UI
#    Browse media → Request → Check logs immediately

Email Notifications Not Working

Symptoms:

  • Test email fails to send
  • Users not receiving notifications
  • SMTP connection errors in logs

Resolution Steps:

  1. Verify SMTP configuration (Settings → Notifications → Email):

    • SMTP Server hostname (e.g., smtp.gmail.com)
    • SMTP Port (465 for SSL, 587 for TLS, 25 for plain)
    • Enable SSL/TLS if required by provider
    • Valid username and password credentials
  2. Test email notification:

    • Settings → Notifications → Email → Send Test Email
    • Check spam folder if test email missing
  3. Check logs for SMTP errors:

    bash
    journalctl -u ombi@username -f | grep -i email
Gmail SMTP Setup
Tip

For Gmail SMTP, use App Passwords instead of your regular password. Generate at Google Account → Security → 2-Step Verification → App passwords. Use port 587 with TLS enabled.

Database Corruption

Symptoms:

  • Ombi crashes on startup
  • Database locked errors in logs
  • Incomplete or missing data in web interface

Resolution Steps:

Take a Full Backup first, and roll back to it if the integrity check fails. The dashboard steps for both are in Back up and restore.

bash
# Stop Ombi service
systemctl stop ombi@username
 
# Take a Full Backup of the install tree and the SQLite databases
qb manage software -o backup -o app -u username -s ombi
 
# Check database integrity
sqlite3 /home/username/.config/Ombi/Ombi.db "PRAGMA integrity_check;"
sqlite3 /home/username/.config/Ombi/OmbiSettings.db "PRAGMA integrity_check;"
 
# If corrupted, roll back to your last Full Backup (saved in /home/username/.QuickBox/software/ombi/backup/)
qb manage software -o rollback -o app -u username -s ombi
 
# Restart Ombi
systemctl start ombi@username
Database Maintenance
Warning

Never manually edit database files while Ombi is running. Always stop the service first, make changes, then restart. A Full Backup holds the SQLite files only; if you migrated Ombi to MySQL, your data is in the MariaDB database, which a Full Backup does not include.



Media Servers

3

Media Management

3

Request Management

2

Additional Resources


Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

  • Dedicated Support
  • Feature Previews
  • Community Configs
  • Active Discussions
Join Discord Server
Last updated on