Path 2 — The companion plugin (for server owners)

Audience: you run a Minecraft server and want your installed plugins kept up to date. No code, no building. You install one plugin and list the others in a config file.

If a term is unfamiliar, see the glossary.

What it is

PluginPulse Companion is a normal plugin you drop into plugins/. It reads a list of your other plugins and where each one publishes updates, then checks (and optionally downloads) updates on their behalf — without those plugins needing to know anything about it.

It never swaps a running jar live: downloaded updates are staged and applied the next time you restart. Safe by default.

1. Download

Get PluginPulseCompanion-<version>.jar from the Releases page.

2. Install

Stop your server (or have it running — either is fine for the first install).
Put the jar in your server's plugins/ folder.
Start (or restart) the server.

On a successful start you'll see in the console:

[PluginPulseCompanion] Enabling PluginPulseCompanion vX.Y.Z
[PluginPulseCompanion] No plugins configured yet — edit config.yml and run /pluginpulse reload.

That last line is expected on a fresh install — you configure it next.

3. Configure

Open plugins/PluginPulseCompanion/config.yml. Here's a complete, worked example for three real-world-shaped plugins:

plugins:
  # Key = the plugin's EXACT name as shown by /plugins.
  EssentialsX:
    modrinth: essentialsx        # its Modrinth slug
    mode: notify                 # tell me on join; don't download

  WorldGuard:
    github: EngineHub/WorldGuard  # its GitHub owner/repo (uses Releases)
    mode: download                # download + stage; applies on restart

  MyPaidPlugin:
    hangar: Author/My-Plugin      # its Hangar project slug
    mode: check-only              # silent; only shown via /pluginpulse

# Sent with API requests. Modrinth's rules require a way to reach you
# (an email or a website/URL).
user-agent-contact: "you@example.com"

# How often to check each plugin, in hours (minimum 1).
check-interval-hours: 6

# Give brand-new releases time to settle before touching them.
hold-new-updates: false
hold-new-updates-hours: 18

Every field explained:

Field	Meaning
`plugins:`	the list of plugins to manage; each key is a plugin's exact name
`modrinth` / `github` / `hangar`	where that plugin's updates come from — see finding your update source. Use exactly one per plugin
`mode`	what to do when an update is found (see below)
`track`	(optional, per plugin) follow a `-<track>` release line, e.g. `track: mc26`
`user-agent-contact`	how the update APIs can reach you; required by Modrinth
`check-interval-hours`	how often to check (minimum 1)
`hold-new-updates`	`true` to leave a release alone until it has been out a while (see below). Default `false`. Can also be set per plugin
`hold-new-updates-hours`	how long that wait is, in hours (minimum 1). Default 18. Can also be set per plugin

Waiting out brand-new releases

Sometimes an author publishes an update that turns out to be broken and puts out a fix a few hours later. If your server picked up the broken one in the meantime, you are stuck with it until the next check comes round.

Switch on hold-new-updates and PluginPulse ignores a release until it has been publicly available for hold-new-updates-hours (18 by default) — long enough that a quick fix-up release lands first. It uses the release date the plugin's own page publishes, so the clock starts when the author released it, not when your server first noticed.

The wait covers everything PluginPulse does on its own: the notices to admins, the downloads and the automatic installs. You are never locked out — /pluginpulse download <plugin> installs the new version straight away, and /pluginpulse shows which releases are being waited out and for how much longer.

What each mode does — in plain terms:

off — ignore this plugin.
check-only — check quietly; the result only shows in /pluginpulse.
notify — check and tell admins (console + on join). Nothing is downloaded.
download — check, download, verify, and stage the update. It applies the next time you restart the server.
auto-stage — like download, but staged automatically as soon as it's found.

After editing, either restart or run /pluginpulse reload.

4. Use

The command is /pluginpulse (aliases /ppc, /pulse), permission pluginpulse.admin (ops have it by default).

/pluginpulse or /pluginpulse list — show each managed plugin and whether an update is available.
/pluginpulse check [plugin|all] — check now.
/pluginpulse download [plugin|all] — download + stage available updates.
/pluginpulse restore [plugin|all] — stage the previous backup of a plugin (undo a bad update), applied on restart.
/pluginpulse reload — re-read config.yml.

How staged updates apply: downloading stages the new jar into the server's update folder. Restart the server and the server swaps it in on boot. There's no live jar-swapping — that's deliberate, so nothing changes underneath a running server.

FAQ

Does it work on Spigot? Yes — Paper, Spigot, and Folia.
My plugin isn't on Modrinth/Hangar. Use github: owner/repo if its releases are on GitHub. If it's published nowhere with an API, the companion can't track it.
Is it safe? By default (notify), nothing is downloaded — you're only informed. Even in download/auto-stage, updates are checksum-verified, the old jar is backed up, and nothing is swapped until you restart.
A plugin shows as "skipped". The companion prints why (not installed, no source configured, mode: off, etc.). Check the name matches /plugins exactly and it has one source.