Plugin Providers

Plugins are resolved and downloaded before your server starts. This happens deterministically across different providers, bringing all your plugin ecosystems into a single API.

Defining Plugins

You declare plugins via the PLUGINS environment variable. It accepts a multiline string where each line represents one plugin.

• Format: provider:identifier[params]@version (params are optional)
• Default: (Empty, no plugins downloaded)

environment:
  PLUGINS: |
    modrinth:luckperms@latest
    hangar:ViaVersion@latest
    # spiget:12345
    url:https://custom.host/plugin-1.0.jar

Providers

The orchestrator supports several plugin repositories. Each provider handles version resolution and platform compatibility differently.

• Modrinth: The modern, fast, open plugin repository. Supports smart filtering for loaders and game versions.
• Hangar: The official PaperMC repository. Excellent support for Paper, Velocity, and Folia.
• SpigotMC (Spiget): Proxies to SpigotMC via Resource IDs.
• CurseForge: The classic home of Minecraft plugins. Requires an API key.
• Direct URLs: Download from any direct link.
• GitHub Releases: Download directly from a GitHub repository's releases.

Version Aliases & Flags

Across most providers, you can use special aliases and flags in the @version part of the spec:

• @latest: Resolves to the highest stable/release version.
• @experimental: Resolves to the latest beta, alpha, or snapshot if available.
• ! flag: Appending ! (e.g., @latest!) forces the orchestrator to ignore compatibility filters. Use this if a plugin is known to work but its metadata is incorrect.

Optional Parameters

Some providers accept additional arguments via the optional [key=value] block placed between the identifier and the version:

PLUGINS: |
  github:plasmoapp/plasmo-voice[regex=plasmovoice-neoforge-1.21.7-.*.jar]@latest

Intelligent Caching & Removal

During the download phase, MauriceNino/minecraft-server builds and manages a .plugin-lock.json file inside its runtime directory.

• Caching: If luckperms@latest resolves to version v5.4.133, this is saved to the lockfile. On the next container boot, it compares the current remote latest version to the lockfile's version. If it matches, the download is skipped instantly.
• Orphan Removal: If you delete a line from your PLUGINS env variable, the orchestrator detects its absence from the lockfile diff, and automatically deletes the .jar from your container, keeping your runtime completely stateless and synchronized.