Installation

Madsi runs as a server-side mod on Fabric and NeoForge, and as a plugin on Paper / Purpur (Folia isn't supported yet). Pick the build for your platform. The link/token flow is the same everywhere.

On Fabric and NeoForge, Madsi hooks into a few places in Minecraft's own code. When another mod changes the same place and a hook can't apply, the server still starts: Madsi logs a warning that names what is off (for example in-game ban reports or the custom whitelist message), and the server's Status page lists it. Everything else keeps working. Updating or removing the other mod and restarting brings it back.

1. Download the latest Madsi JAR for your platform from the download page or Modrinth
2. Place the JAR in mods/ (Fabric / NeoForge) or plugins/ (Paper / Purpur)
3. On Fabric, make sure Fabric API is also in mods/
4. Start (or restart) your Minecraft server

On first launch, Madsi creates config/madsi.json with an empty token field.

The mod stores its configuration in config/madsi.json. The only required field is token, which you get from the dashboard.

{
  "token": "your-server-token"
}

After adding the token and restarting, check the server's Status page in the dashboard. Your server should appear as Connected within a few seconds.

You can also run /madsi status in-game to confirm the connection from the Minecraft side.

If the server doesn't connect, see Troubleshooting > Server not connecting.

To update, simply replace the old JAR with the new one and restart your server. Your config/madsi.json is preserved. You don't need to regenerate your token.

An update always applies on a restart. No Minecraft loader can swap a mod or plugin's code in a running server (the classes are loaded once at launch) so Madsi downloads and verifies while you're online and the new build takes effect the next time the server starts.

Madsi checks on startup and every six hours after that. When a newer build exists it tells the console and every operator online, and repeats the notice to each operator as they join, so a release published while nobody was looking isn't missed. The join notice follows the madsi.updatenotify permission on every loader: operators have it by default, and a permissions mod or plugin can grant it to anyone.

• /madsi update: check and report. Nothing is downloaded.
• /madsi update confirm: download, verify, and put the new build in place for the next restart.
• Update Madsi automatically on the server's Settings page: do that automatically whenever a newer build appears. Off by default. The dashboard owns this setting (and update checks and the stats interval) and writes it to config/madsi.json, so set it there rather than in the file.

Fabric and NeoForge replace the jar in the mods folder directly. Paper can't safely overwrite a plugin jar that the server still has open, so Madsi stages the new build in Bukkit's update folder and the server installs it during the next startup. The same mechanism you'd use to update any plugin without downtime.

After it replaces its own jar, Madsi removes the copy of itself it just superseded, so the folder never ends up with two builds the loader has to choose between. It only ever removes a file it can prove is a superseded copy of Madsi: the jar has to declare Madsi's mod id in its own descriptor and carry Madsi's compiled code, and its version has to be lower than the build being kept, or byte-for-byte identical to it. Anything else is left where it is and named in a warning instead, including a build newer than the one running and a jar for a different Minecraft version. Renaming a jar so it no longer ends in .jar, or keeping it outside the mods folder, puts it out of reach entirely. On Paper nothing is ever removed, because Bukkit holds every plugin jar open.

The server also tells the dashboard, so you don't have to be in game to find out: the Status page shows what's pending and whether it's already downloaded, and the Madsi update available event can be routed to a Discord channel like any other (Bridge → event routing). It's posted once per build rather than on every six-hourly check, and clears itself when the server reconnects running that version.

Installed mods on the Status page lists every mod or plugin the server reports, each one checked against Modrinth for your exact loader and Minecraft version. Sort by name, by the order the server lists them, or by what needs updating; filter by status or search by name or author when a pack runs to a few hundred. Click a row to open that mod's own page: its icon, version, size, file, licence and links, plus the Modrinth gallery and description when Modrinth knows the file. The link icons on the row still go straight to Modrinth, the source or the issue tracker. Add mods at the top of the list searches Modrinth for mods (or plugins, on Paper) built for this server's loader and Minecraft version that run on a server, sorted by relevance, downloads, followers, newest or recently updated, filtered by category, and with Hide installed leaving out what the server already has; Install downloads the newest release and anything it requires, checked against Modrinth's SHA-512, and it loads on the next restart. Disable, on a mod's own page, renames its jar to end in .disabled so the server skips it; it moves to Disabled mods at the bottom of the list, where Enable puts it back. Delete removes it for good: Madsi lists the jar, the config files the mod's loader or config library says are its own (ticked), and files merely named after it (unticked, for you to choose), and you type the mod's name to confirm. A running mod's jar goes at once and its files at the next start, so it can't write them back as it stops. Blocks and items it added stay in the world save until Minecraft clears them, so back up first. Both warn if another mod needs it, and everything takes effect on the next restart. They need the Mods permission and follow the same Install mod updates switch as updates; disabling or deleting a proxy forwarding mod (FabricProxy-Lite, Proxy-Compatible-Forge, NeoVelocity, NeoForwarding, BungeeGuard) or a login or permission plugin (LuckPerms, AuthMe and the like) also needs Guarded config, as editing its config does.

Each outdated row has an Update button, and Update all works through every outdated mod one at a time. Madsi downloads the build Modrinth publishes, verifies its SHA-512, and puts the jar in the mods folder (on Paper, in Bukkit's update folder). Like every other update, it loads on the next restart, and the row says so until then. Restart to apply, at the top of the list, does that last step without leaving the page. Installing needs the owner or a team role with the Mods permission.

The jar an update replaces, and the mods a modpack takes out, are kept in .madsi/removed-mods. Madsi keeps the jars of the newest 3 removals and deletes older jars; configs a modpack replaced are never deleted. They're listed under Removed mods below the installed list: Restore puts one back in the mods folder for the next restart (only into the world it came from; one Madsi can't tie to a world can only be deleted), Delete removes the kept jar for good. Both need the Mods permission.

• A mod Modrinth doesn't recognise is listed with a warning beside its links. A build Modrinth never saw (one from GitHub, say) is matched to its project only when the jar's own author list or repository vouches for it, and the row says matched by id or matched by name.
• Hover a version to see the jar's file name.
• A mod ahead of the newest release (a beta or dev build) is left alone rather than downgraded.
• Downloads only ever come from Modrinth's CDN or madsi.link, and a jar whose hash doesn't match is discarded.
• Turn it off per server with Install mod updates on its Settings page (needs the Mods permission), or on the machine itself with allowModInstall: false in config/madsi.json. The config wins.

Each mod's page lists its config files. Open one to read it as a manual: the file's own notes at the top, its sections, and one compact row per setting, with the comment its author wrote for it behind the info icon (hover or tap it). The search box above the settings finds a setting by its name, value or description, and images from Modrinth, GitHub, Imgur and CurseForge show inside the description. Defaults, ranges and allowed values written in those comments show as small labels, and settings that are only written out as a comment show as Commented out. Raw shows the file exactly as it is on the server.

On Paper each plugin's own folder belongs to it, so its files are listed with certainty. On NeoForge, and on Fabric for mods that use Forge Config API Port or MidnightLib, the mod registered its config itself, so Madsi knows which file is whose and opens it as a proper form. For mods that use Cloth Config or owo-lib, Madsi reads the config's definition from the mod's jar, so each setting shows under the mod's own name for it, with its limits and options; the values are still changed in the file. Any other mod keeps its configs in the shared config folder, so there Madsi lists the files named after the mod and says it is a guess. A link to an image in a comment loads only when you ask; a YouTube link opens YouTube.

To change a file, edit a value in Settings (a switch, a list of the options its comment names, or a text box) or edit the text in Raw; both change the same draft. Madsi only ever replaces the characters of the values you changed, so comments, blank lines, key order and line endings stay exactly as they were. Save shows the change as a diff, then the server checks the new text with the parser that will load it and refuses a save it couldn't load, naming the line. It keeps a backup of the old file on the server before swapping the new one in. Plugins read their config when they start, so a change applies on the next restart; for plugins with their own reload command (EssentialsX, LuckPerms, WorldGuard and others), Madsi offers to run it for you if you have the Guarded config and Run commands permissions.

The server's own files (server.properties on every loader, and spigot.yml, paper-global.yml and paper-world-defaults.yml on Paper) are under Settings → Server files. The server reads them before Madsi loads, so a broken one would stop it starting: they change only through their settings, each value keeps its type, nothing can be added or removed, and the server refuses a save it couldn't start from, naming the setting. Changes apply on the next restart. A file with a password in it can still be edited; the hidden value is never touched. Settings that open a remote console (RCON and the management server) and spigot.yml's restart script can only be changed on the machine itself; changing restart-on-crash or timeout-time needs Guarded config.

On NeoForge, a config the mod registers with NeoForge opens as a form built from the mod's own definition: every setting it declares, the right control for its type, its allowed range, and whether it needs a restart. Change what you need and press Save. Sync now writes it at once; NeoForge reloads it straight away and sends server settings to everyone online. Sync when no players are online keeps the change on the server and writes it when the last player leaves, or when the server stops (or, if the server crashed first, once it is back up and connected while nobody is online), and the file shows that it is waiting until then. If nobody is online when you save, it is written straight away. If the file changes on the server first, or config editing is switched off, the waiting change is dropped and the page says so. Each save keeps a backup of the previous file on the server.