VonixGuardian Vonix Mods v2.3.2 Search GitHub
VonixGuardian/Installation

Installation#

VonixGuardian is a server-side mod. Install it on the dedicated server or the integrated server; never on clients.

Before you start#

Check that your server matches one of the supported combinations.

Minecraft Fabric Forge NeoForge Java
26.3 ✅ — ✅ 25
26.2 ✅ — ✅ 25
26.1.2 ✅ — ✅ 25
1.21.1 ✅ — ✅ 21
1.20.1 ✅ ✅ — 17
1.19.2 ✅ ✅ — 17
1.18.2 ✅ ✅ — 17

You also need write access to the server directory, since the mod creates config/vonixguardian/, logs/vonixguardian/, and a database file on first boot.

Disk space

The audit database grows with activity. Plan for several hundred megabytes on a busy server. purge.autoPurgeSeconds ships as 0, which keeps every row until you set a retention horizon — see Configuration.

Download the right jar#

CurseForge is the recommended download if you use a launcher or modpack: https://www.curseforge.com/minecraft/mc-mods/vonix-guardian/files

Every release is also published on GitHub: https://github.com/Vonix-Network/VonixGuardian/releases

Pick the one jar matching your loader and Minecraft version. Both sources carry identical bytes; the checksums below match either.

vonixguardian-fabric-26.3-2.3.2.jar
vonixguardian-neoforge-26.3-2.3.2.jar
vonixguardian-fabric-26.2-2.3.2.jar
vonixguardian-neoforge-26.2-2.3.2.jar
vonixguardian-fabric-26.1.2-2.3.2.jar
vonixguardian-neoforge-26.1.2-2.3.2.jar
vonixguardian-fabric-1.21.1-2.3.2.jar
vonixguardian-neoforge-1.21.1-2.3.2.jar
vonixguardian-fabric-1.20.1-2.3.2.jar
vonixguardian-forge-1.20.1-2.3.2.jar
vonixguardian-fabric-1.19.2-2.3.2.jar
vonixguardian-forge-1.19.2-2.3.2.jar
vonixguardian-fabric-1.18.2-2.3.2.jar
vonixguardian-forge-1.18.2-2.3.2.jar

Also download SHA256SUMS from the same release.

Verify the download#

Check the jar against the published checksums before it goes anywhere near a server.

curl -LO https://github.com/Vonix-Network/VonixGuardian/releases/download/v2.3.2/vonixguardian-forge-1.20.1-2.3.2.jar
curl -LO https://github.com/Vonix-Network/VonixGuardian/releases/download/v2.3.2/SHA256SUMS.txt
sha256sum -c SHA256SUMS --ignore-missing

A good download prints OK for the jar you fetched:

vonixguardian-forge-1.20.1-2.3.2.jar: OK

Do not run an unverified jar

A FAILED line means the file is corrupt or was tampered with. Delete it and download again. Never install a mod jar whose checksum does not match.

Install#

  1. Stop the server cleanly. Use /stop from the console, or the panel's stop control — not kill.
  2. Wait for the process to exit. On panel-managed hosts, confirm the container is stopped before touching files.
  3. Copy the verified jar into the server's mods/ directory.
  4. Start the server.
cp vonixguardian-forge-1.20.1-2.3.2.jar /path/to/server/mods/

That is the whole install. There is no separate library, coremod, or config file to stage first.

Remove older copies

If mods/ still holds a VonixGuardian jar from another Minecraft version or loader, remove it. Two copies of the mod loading at once produces confusing duplicate-registration errors.

First boot#

No launch flags, no JVM arguments. Start the server as usual.

Relative to the server root, the mod creates:

Path Contents
config/vonixguardian/config.json Generated on first boot with defaults.
config/vonixguardian/worlds/ Optional per-world overrides. Not created until you add one.
vonixguardian.db The SQLite database (default backend).
logs/vonixguardian/ Rolling JSON-Lines audit log.
blacklist.txt Optional. You create this yourself to suppress specific logging.

Verify the install#

Two log lines confirm success, both under the VonixGuardian logger marker.

The load line appears early:

[main/INFO] [VonixGuardian]: VonixGuardian (Forge 1.20.1) loading.

The bootstrap line appears after the engine is up, the schema is initialised, and the command tree is registered:

[Server thread/INFO] [VonixGuardian]: VonixGuardian bootstrap complete.

bootstrap complete. is printed before Minecraft's own Done (Xs)! line. If Done prints and bootstrap complete. never does, treat the install as failed.

Once players can log in, check the runtime surface:

/vg status

You should see the version, storage backend and schema version, writer-queue depth, permissions mode, and public API version. A healthy fresh install shows zero drops and a low queue depth.

Upgrading#

  1. Stop the server.
  2. Replace the old jar in mods/ with the new one for the same loader and Minecraft version.
  3. Start the server.

Schema migrations run automatically at boot and are idempotent. The current schema is v9. Existing rows, rollback batches, and configuration keys are preserved; new config fields are filled in from safe defaults when absent. See Database & storage for what each version adds.

Check open rollback batches after an upgrade

/vg status lists any rollback batch that did not complete. Boot never replays an open batch — that is deliberate, so a half-applied rollback is not finished twice. Inspect the listed batch ids before re-running anything.

Uninstalling#

  1. Stop the server.
  2. Remove the jar from mods/.
  3. Start the server.

The world itself is unaffected. vonixguardian.db, config/vonixguardian/, and logs/vonixguardian/ are left in place; delete them manually if you do not want to keep the audit history.

Next steps#