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

Note

You can comment out individual plugins by prefixing the line with #.

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

Note

Not all providers support extra parameters. Check each provider's documentation page for the list of available arguments.

Intelligent Caching & Removal

During the download phase, MauriceNino/minecraft-server builds and manages a server-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.

Development Check Cache (`PLUGINS_CHECK_CACHE`)

When iterating quickly — e.g. restarting your development server many times — the orchestrator would otherwise hit provider APIs on every boot. PLUGINS_CHECK_CACHE defaults to 5m, meaning existing plugins are only re-checked at most once every 5 minutes. You can override it:

environment:
  PLUGINS_CHECK_CACHE: 30m  # only re-check existing plugins every 30 minutes
  # PLUGINS_CHECK_CACHE: 0s  # disable the cache and always check on startup

The timestamp of the last full check is stored in server-lock.json. While the cache is valid:

Existing plugins are skipped — no API calls, no version comparisons.
New plugins are still installed — any plugin added to PLUGINS that isn't already in the lockfile will be downloaded.
Removed plugins are still cleaned up — orphan .jar files are deleted as usual.

The mc-orchestrator update command always bypasses this cache and performs a full update.

Update Strategies

You can control how the orchestrator handles plugin downloads and updates via the PLUGINS_UPDATE_STRATEGY environment variable.

Strategy	Behavior
`manual`	Checks for updates and removes orphans, downloads newly added plugins, but never updates to new versions. Use this if you want to see what's available without changing your jars.
`auto`	(Default) Checks for updates, downloads them, and removes orphans. If a download fails, it logs an error but continues starting the server with the old version.
`force`	Same as `auto`, but the orchestrator will abort the startup and fail if any plugin fails to download or resolve.