Plugin Manifest Reference

Every plugin must include a omnilux-plugin.json file at its root. This file describes the plugin to OmniLux's loader.

Full schema

{
  "name": "omnilux-plugin-example",
  "version": "1.0.0",
  "displayName": "Example Plugin",
  "description": "A description of what this plugin does",
  "category": "notification-agent",
  "icon": "bell",
  "author": "Your Name",
  "license": "MIT",
  "compatibility": {
    "omnilux": ">=0.1.0",
    "api": ">=1"
  },
  "dependencies": [
    {
      "name": "omnilux-plugin-other",
      "version": ">=1.0.0",
      "optional": false
    }
  ],
  "permissions": [
    "network:outbound",
    "notifications:send"
  ],
  "entry": "src/index.ts",
  "adapters": [
    {
      "type": "NotificationAgentAdapter",
      "id": "my-agent",
      "displayName": "My Agent",
      "description": "Sends notifications to my service"
    }
  ],
  "routes": [
    {
      "path": "/api/my-plugin/webhook",
      "method": "POST",
      "description": "Receive webhooks from my service"
    }
  ],
  "settingsUI": {
    "entry": "src/ui/settings.ts",
    "tabId": "my-plugin",
    "displayName": "My Plugin Settings"
  },
  "migrations": [
    {
      "id": "001-create-tables",
      "path": "migrations/001-create-tables.sql",
      "description": "Create plugin tables"
    }
  ],
  "backgroundJobs": [
    {
      "id": "my-sync-job",
      "schedule": "15m",
      "description": "Sync data every 15 minutes"
    }
  ]
}

Field reference

Required fields

Field	Type	Description
name	string	Unique plugin identifier. Must be lowercase, alphanumeric with hyphens. Convention: omnilux-plugin-<name>
version	string	SemVer version string (e.g., 1.0.0)
displayName	string	Human-readable name shown in the UI
description	string	Short description of the plugin's purpose
category	PluginCategory	Plugin category (see below)
compatibility	object	Version constraints
permissions	Permission[]	Required permissions (see Permissions)
entry	string	Path to the plugin's entry point (must export a register function)

Optional fields

Field	Type	Description
icon	string	Icon name or emoji for the plugin
author	string	Author name
license	string	SPDX license identifier
dependencies	PluginDependency[]	Other plugins this plugin depends on
adapters	PluginAdapterManifest[]	Adapters this plugin provides
routes	PluginRouteManifest[]	API routes this plugin registers
settingsUI	PluginSettingsUiManifest	Settings panel registration
migrations	PluginMigrationManifest[]	Database migrations
backgroundJobs	PluginBackgroundJobManifest[]	Scheduled background jobs

Categories

Category	Description
download-client	Download client integration
indexer	Search indexer
vpn	VPN management
scanner	File scanning
search	Search pipeline
iptv-source	IPTV channel sources
game-source	Game download sources
notification-agent	Notification delivery
metadata-provider	Metadata lookups
arr-service	*arr stack interop
integration	External service integration
ui	UI enhancements
utility	General utilities

Compatibility

{
  "compatibility": {
    "omnilux": ">=0.1.0",
    "api": ">=1"
  }
}

• omnilux — required. SemVer range for compatible OmniLux versions
• api — optional. API version constraint

Dependencies

{
  "dependencies": [
    {
      "name": "omnilux-plugin-other",
      "version": ">=1.0.0",
      "optional": false
    }
  ]
}

• name — plugin name to depend on
• version — SemVer range
• optional — if true, the plugin loads even if the dependency is missing

Adapter manifest

{
  "type": "NotificationAgentAdapter",
  "id": "my-agent",
  "displayName": "My Agent",
  "description": "Description shown in the UI"
}

• type — must match a valid AdapterKind
• id — unique identifier for this adapter within its type

Route manifest

{
  "path": "/api/my-plugin/webhook",
  "method": "POST",
  "description": "Receive incoming webhooks"
}

• method — HTTP method. Defaults to GET if omitted

Background job manifest

{
  "id": "my-sync-job",
  "schedule": "15m",
  "description": "Sync data periodically"
}

• schedule — interval string: 30s, 5m, 1h, 24h, etc.

Validation rules

• name must be unique across all installed plugins
• version must be a valid SemVer string
• entry must point to an existing file
• permissions must only contain valid Permission values
• adapters[].type must be a recognized AdapterKind
• migrations must have unique id values and existing path references

Invalid manifests are rejected at install time with descriptive error messages.