Skip to content
Vonix Network Wiki

VonixGuardian — Installation Guide

State: 3.0.0-m1 testing candidate — publication pending

Public download URLs are not published here. Use the matching loader/version jar from your owner-controlled testing channel. Do not treat this snapshot as a production release.

Publication pending

VonixGuardian is a strictly server-side mod. It does not need to be installed on player clients. Clients join using standard vanilla, Fabric, Forge, or NeoForge launchers; only the dedicated server requires the jar in its mods/ directory.

1. Prerequisites

Section titled “1. Prerequisites”

Before installing, ensure your host environment satisfies the following:

  1. Minecraft Server Environment: A clean or existing server running one of the 9 supported loader cells.
  2. Java Runtime: The installed Java version must match your target Minecraft version:
    • Minecraft 26.1.2: Java 25
    • Minecraft 1.21.1: Java 21
    • Minecraft 1.20.1 / 1.19.2 / 1.18.2: Java 17
  3. Filesystem Permissions: The server process must have read/write access to the server directory to create config/vonixguardian/, logs/vonixguardian/, and the local SQLite database file.
  4. Storage Space: Allow a minimum of 1–5 GB of free disk space depending on player activity and configured purge retention.

2. Supported Cell Artifacts

Section titled “2. Supported Cell Artifacts”

Nine loader cells are packaged in the 3.0.0-m1 testing matrix. Select the exact jar matching your loader and Minecraft version:

Minecraft Version Mod Loader Expected Artifact Name Java Required Packaging Model
26.1.2 NeoForge vonixguardian-neoforge-26.1.2-3.0.0-m1.jar Java 25 ModDevGradle jarJar
1.21.1 NeoForge vonixguardian-neoforge-1.21.1-3.0.0-m1.jar Java 21 net.neoforged.moddev jarJar
1.21.1 Fabric vonixguardian-fabric-1.21.1-3.0.0-m1.jar Java 21 Loom JarInJar (META-INF/jars)
1.20.1 Forge vonixguardian-forge-1.20.1-3.0.0-m1.jar Java 17 ForgeGradle 6 jarJar
1.20.1 Fabric vonixguardian-fabric-1.20.1-3.0.0-m1.jar Java 17 Loom JarInJar (META-INF/jars)
1.19.2 Forge vonixguardian-forge-1.19.2-3.0.0-m1.jar Java 17 ForgeGradle 6 jarJar
1.19.2 Fabric vonixguardian-fabric-1.19.2-3.0.0-m1.jar Java 17 Loom JarInJar (META-INF/jars)
1.18.2 Forge vonixguardian-forge-1.18.2-3.0.0-m1.jar Java 17 ForgeGradle 6 jarJar
1.18.2 Fabric vonixguardian-fabric-1.18.2-3.0.0-m1.jar Java 17 Loom JarInJar (META-INF/jars)
Library Packaging Safety

VonixGuardian nests its SQLite JDBC driver (sqlite-jdbc-3.46.1.0.jar) using loader-native JarInJar packaging. This preserves the canonical JNI symbols required by NativeDB and prevents UnsatisfiedLinkError crashes. Do not attempt to shade or extract the driver manually.

3. Installation Steps

Section titled “3. Installation Steps”

Step 1: Stop the Server

Section titled “Step 1: Stop the Server”

Always shut down the Minecraft server cleanly before installing or upgrading mods:

Terminal window
# In console or in-game as op
/stop

Step 2: Place the Artifact

Section titled “Step 2: Place the Artifact”

Copy the single matching candidate jar into your server’s mods/ folder:

Terminal window
# Example for a 1.21.1 Fabric server
cp vonixguardian-fabric-1.21.1-3.0.0-m1.jar /path/to/server/mods/

Step 3: Verify Integrity

Section titled “Step 3: Verify Integrity”

If you have a local verification checksum file, verify the SHA-256 hash before launch:

Terminal window
sha256sum vonixguardian-fabric-1.21.1-3.0.0-m1.jar

Step 4: Boot the Server

Section titled “Step 4: Boot the Server”

Start your Minecraft server using your standard launcher script or container manager.

4. First Boot Verification

Section titled “4. First Boot Verification”

During startup, VonixGuardian automatically creates the following directories and files:

  • config/vonixguardian/config.json — Configuration defaults.
  • vonixguardian.db — Default local SQLite database file in the server root.
  • logs/vonixguardian/audit-YYYY-MM-DD.log — Rolling JSON-Lines audit stream.

Key Startup Log Signals

Section titled “Key Startup Log Signals”

Check your logs/latest.log to confirm proper initialization. You should observe two distinct messages:

  1. Mod Load Banner: 
    [Server thread/INFO] [VonixGuardian]: VonixGuardian (Fabric 1.21.1) loading.
  2. Bootstrap Completion: 
    [Server thread/INFO] [VonixGuardian]: VonixGuardian bootstrap complete.
Validation Rule

The VonixGuardian bootstrap complete. line must appear before Minecraft’s own [Server thread/INFO]: Done (Xs)! For help, type “help” banner. If the server finishes loading without emitting this line, the mod was either skipped by the loader or experienced a silent boot failure.

5. Health Check Command

Section titled “5. Health Check Command”

Once the server has fully booted and ops have connected, execute:

/vg status

Expected output includes:

  • Storage Backend: sqlite (active connection stats)
  • Writer Queue: Current queue depth (should be 0 or low under idle conditions) and dropped action count (0)
  • Schema Version: 8
  • Candidate Release Line: 3.0.0-m1

6. When This Does Not Apply

Section titled “6. When This Does Not Apply”
  • Client Installations: Do not place this mod into player client directories. Fabric and NeoForge will ignore server world hooks on client single-player, but it wastes memory and is unsupported.
  • Paper / Purpur / Spigot: VonixGuardian is strictly for modded loaders (Fabric, Forge, NeoForge). On Bukkit-based servers, use native Bukkit auditing tools like CoreProtect.
  • Live public servers: 3.0.0-m1 is a testing candidate. Evaluate it on a disposable or owner-controlled server before using it as the only audit trail.