Plugin Overview
This section is for developers and advanced operators. If you are trying to use OmniLux as an end user, go back to the main guides.
OmniLux's plugin system is the mechanism through which major features and integrations are delivered. Core functionality and optional extensions use the same adapter interfaces and registration system.
Core vs plugin
There's no feature paywall. All features ship with OmniLux and are available to every user. The plugin architecture is an engineering pattern, not a monetization strategy:
- Built-in plugins — ship with OmniLux: themes, metadata providers, notification agents, and more
- Marketplace plugins — curated, reviewed additions published to the OmniLux marketplace
- Community plugins — third-party plugins from GitHub or other sources, not reviewed by the OmniLux team
What plugins can do
Plugins register adapters that implement standard interfaces:
| Adapter type | Purpose | Examples |
|---|---|---|
DownloadClientAdapter | Download client integration | Third-party download managers |
IndexerAdapter | Search indexer integration | Content search providers |
VpnAdapter | VPN management | WireGuard, SOCKS5 |
ScannerAdapter | File scanning (antivirus, etc.) | ClamAV |
SearchAdapter | Search pipeline (scoring, auto-grab, RSS) | Request pipeline |
IptvSourceAdapter | IPTV channel sources | iptv-org, custom M3U |
GameSourceAdapter | Game source integration | Game library sources |
NotificationAgentAdapter | Notification delivery | Discord, Telegram, Slack, Email |
MetadataProviderAdapter | Metadata lookups | TMDB, TVDB, MusicBrainz, IGDB |
Beyond adapters, plugins can also:
- Register routes — mount API endpoints at any path
- Register background jobs — scheduled tasks that run on an interval
- Register settings panels — add UI to the Settings page
- Run database migrations — create and manage plugin-specific tables
- Emit and listen to events — inter-plugin communication via the event bus
Plugin routes
Plugin routes mount at their original API paths, not under a /api/plugins/ prefix. This means a plugin that registers POST /api/downloads/add intercepts the same path as the core route. Route isolation ensures plugins can only access paths their manifest declares.
Architecture
┌──────────────────────────────────────────┐
│ OmniLux Server │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Plugin A │ │ Plugin B │ │ Plugin C │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ┌────▼─────────────▼─────────────▼─────┐ │
│ │ Plugin Context │ │
│ │ • registerAdapter() │ │
│ │ • registerRoutes() │ │
│ │ • registerJob() │ │
│ │ • db / settings / log / events │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Permission Sandbox │ │
│ │ network / storage / database / ui │ │
│ └──────────────────────────────────────┘ │
└──────────────────────────────────────────┘Each plugin receives a PluginContext on registration. The context is sandboxed: a plugin can only perform actions its declared permissions allow.