How VoxelBench Works
VoxelBench has two halves: a plugin that measures, watches and profiles your Minecraft server, and voxelbench.com, which scores, ranks, compares and alerts. This page follows everything that travels between the two: who starts it, how it is authenticated and where it ends up.
Two Halves
The Plugin, on Your Server
The VoxelBench plugin runs inside your Paper, Spigot or Folia server. It does three jobs:
- Measure. A full benchmark (
/bench start), a stress limit that looks for the server's breaking point (/bench stresslimit), a single test (/bench test) or a custom profile. The plugin runs the tests; the score is computed by voxelbench.com. - Watch. Once remote monitoring is on, it sends the server's figures every minute, a heartbeat every 30 seconds and the events it detects. It also has its own web dashboard, which voxelbench.com does not need.
- Profile. A profiler that shows which plugins use the tick time, and a memory inspection that shows which plugins hold the memory. Their results stay on the server unless you send one yourself.
To install it and run a first benchmark, see Getting Started.
The Website
voxelbench.com turns what the plugin sends into something you can use:
- It scores every benchmark (see How Scoring Works).
- It ranks public reports on the leaderboard and compares servers and hosting offers.
- It keeps your reports, single-test results, profiles and memory reports in your account.
- It monitors your servers with live charts and alerts you on the site, by email or on Discord (see Monitoring Overview).
- It benchmarks on its own with auto-bench, by sending a bot to your server (see Auto-bench on the Website).
- It answers scripts and agents through its API and its connector for Claude (see API and Tokens and Connect Claude to Your Account).
The leaderboard, the statistics, the hosting pages and public reports are open to everyone, without an account.
Every Exchange at a Glance
| Exchange | Started by | What travels | How it is authenticated | Where it ends up |
|---|---|---|---|---|
| Benchmark or stress limit report | The plugin, at the end of a run | The results, and the server's hardware and software as filtered by the plugin's anonymization level | A one-time challenge that only an official VoxelBench jar can answer, plus the server's link token if it is linked | A report page; your account if the server is linked |
| Single test result | The plugin, after /bench test, if you turned result sending on | One test's result | The same challenge, plus the link token (the server must be linked) | Unit tests in your dashboard, private |
| Linking | You, with /bench link | The server's identity, then a link token back to the plugin | An 8-character code that you type on the site while signed in | Servers in your dashboard |
| Verification | You, from the server's page on the site | A code that the plugin hides in the server's status response | voxelbench.com pings your server and looks for the code | The Verified badge on the server |
| Remote monitoring | The plugin, once monitoring is on at both ends | Heartbeats, snapshots of the server's figures, events | The link token | Monitoring in your dashboard, and your alerts |
| Auto-bench | voxelbench.com, on a schedule or on demand | A bot joins your server and gives the plugin a one-time code | The plugin asks voxelbench.com to confirm the code for this server; official jars only | A report or test result attached to the run |
| Profile or memory report upload | You, with a command | One file, as it is | The link token | Profiles or Memory in your dashboard, private |
| Profile or memory report share | You, with a command | A cleaned copy of one file | The same challenge as reports; official jars only | A public, unlisted link, for 7 days |
| Update check | The plugin, at startup | Its version number | None | A notice in the console and in game |
A heap dump never travels: no command, button or automatic path sends one.
Benchmark Reports and Single Tests
When a benchmark or a stress limit run ends, the plugin sends its results to voxelbench.com, whether the server is linked or not. A custom profile run is sent only when its profile says submit: true.
Before sending, the plugin proves that it is an official build. It asks voxelbench.com for a challenge, valid 5 minutes and usable once, and answers it with a signature that only official builds can produce. voxelbench.com also compares the fingerprint of the jar with the official releases it knows: a rebuilt or modified jar is refused. How much the report says about your hardware depends on the plugin's anonymization level (see Privacy & Security).
What becomes of the report depends on whether the server is linked:
- Not linked: the report is anonymous. Anyone who has its link can open it, and it expires after 30 minutes.
- Linked: the plugin adds the server's link token, and the report goes to your account, private by default; it is kept 30 days on Free and 1 year on Pro, Enterprise and hosting provider accounts (see Plans & Limits). You then decide who sees it (see Public, Unlisted or Private).
A single test result (/bench test) is sent only when reports.backend.unit-tests is true in the plugin's configuration and the server is linked. It is kept privately in your account (see Unit Tests).
Linking and Verifying a Server
Linking and verifying prove two different things. Monitoring, uploads and single tests need a linked server; auto-bench needs a server that is linked and verified.
Linking: This Server Belongs to My Account
- Run
/bench linkon the server. The plugin asks voxelbench.com for an 8-character code, valid 10 minutes, and shows it with a link. - Open the link, or go to Servers โ Link a server in your dashboard, sign in and type the code. Your account's email address must be verified.
- The plugin, which checks every 5 seconds for 5 minutes, receives a link token and saves it in its configuration.
The code proves that whoever types it can read the server's console. voxelbench.com hands the token only to the address that asked for the code, and afterwards keeps only a fingerprint of it. From then on, the plugin sends that token with its reports, test results, monitoring and uploads: this is how voxelbench.com knows they belong to your account. Details: Server Linking and Account Linking.
Verifying: I Control the Server at This Address
- On the linked server's page, in Server Verification, enter the server's public address. The site gives you a code such as
VOXEL-A1B2C, valid 10 minutes. - Run
/bench verify <code>on the server. The plugin tells voxelbench.com, and hides the code in the server's status response, the one the multiplayer server list reads. - Click Verify Server. voxelbench.com pings the address and looks for the code.
A server can be verified by one account only. The verified address is the one the auto-bench bot connects to. Details: Server Verification.
Remote Monitoring
Remote monitoring needs a plan that includes it (Pro, Enterprise or a hosting provider account) and two switches: monitoring turned on for the server on voxelbench.com, and remote-monitoring.enabled in the plugin, which /bench monitor remote on sets for you. The plugin then sends:
- a heartbeat every 30 seconds, so voxelbench.com knows that the server is up and that its main thread still ticks;
- a snapshot of the server's figures (TPS, tick times, memory, CPU, garbage collection, counts), taken and sent every 60 seconds by default;
- the events it detects, as they happen.
Every request carries the server's link token. Snapshots contain no player names; moderation events do, if you turn on the LiteBans integration. Everything ends up on the Monitoring page of your dashboard, where your alert rules watch it. Setting it up: Monitoring Overview; on the plugin side: Monitoring.
Auto-bench
Auto-bench is the one exchange that voxelbench.com starts. On a schedule, or when you click Run now, it sends a bot, a Minecraft: Java Edition client with no screen, which joins your server like a player and types /vbautobot with a one-time code. The plugin asks voxelbench.com whether that code is valid for this server, and only then runs what voxelbench.com asks for (mode, test or profile, warm-up, number of runs), never what the bot typed. The results travel like any report, attached to the run, and the bot disconnects. Here too, only official jars are accepted.
Website side: Auto-bench on the Website. Server side: Auto-bench.
Profiles and Memory Reports
The profiler and the memory inspection keep their results on the server. A result leaves only when an operator types the command, one at a time, and never during a scored run. Adding preview to the command shows what would leave, and sends nothing until you confirm:
| Command | What leaves | Where it ends up |
|---|---|---|
/bench profile upload <id>, /bench memory upload <id> | The file as it is, authenticated with the link token (the server must be linked) | Your account, private: Profiles or Memory in your dashboard |
/bench profile share <id>, /bench memory share <id> | A cleaned copy, without addresses, file paths or the names of players, worlds and the machine | A public, unlisted link that anyone who has it can open, without an account, for 7 days |
A share is signed like a report, so only official jars can share. /bench profile unshare <id> and /bench memory unshare <id> delete the link before it expires.
How many uploads your account keeps depends on your plan: 5 of each kind for 30 days on Free, 50 for 180 days on Pro, 200 for a year on Enterprise and on hosting provider accounts. A short summary of each profile is kept a year on every plan.
A heap dump never leaves the server. It holds everything the server had in memory, the link token included. Only the summaries and analyses made from it can be sent, and the analysis runs on your own machine. Details: Profiling and Memory Inspection.
Plugin Updates
About 5 seconds after startup, the plugin asks voxelbench.com whether a newer version exists, sending its version number. If there is one, it says so in the console, and in game to operators and to players with voxelbench.admin, with a download link. It never downloads or installs anything by itself; update-check: false turns the check off (see Configuration).
The latest release is on the Download page. Since voxelbench.com only accepts the jars it knows, install the official file as it is.
Public, Unlisted or Private
| What | Who can see it |
|---|---|
| Report from a server that is not linked | Anyone who has its link, for 30 minutes |
| Report from a linked server | You, whoever holds the server once they have verified it, and VoxelBench administrators, until you change its visibility to Unlisted (anyone who has the link can open it; it appears in no list of other people and search engines are asked not to index it) or Public (listed, and eligible for the leaderboard). Only you, its author, change its visibility: when VoxelBench links a public report to a hosting offer, its visibility and lifetime stay as they are. Publishing or sharing it by link requires a verified email address, and a custom profile report cannot be public |
| Single test result | You, whoever holds the server once they have verified it, and VoxelBench administrators |
| Certification report of a hosting plan | VoxelBench only, until the hosting provider approves the certification; then everyone, marked Certified, even after the certification has expired |
| Uploaded profile or memory report | Only you |
| Shared profile or memory report | Anyone who has the link, for 7 days; search engines are asked not to index it |
| Monitoring data, events and alerts | Only you. You may open a public status page for a server: it says whether the server is up, never a measurement or a player name |
| Linked servers, auto-bench targets and runs | Only you |
| Heap dump | Nobody: it never leaves the server |
Accounts and Plans
- Without an account, you can browse the leaderboard, the statistics, the hosting pages and public reports, and call the public API 10 times a day from one address.
- A free account links servers, keeps their reports and single-test results, receives profiles and memory reports, and holds one API token.
- Pro adds remote monitoring (one server) and auto-bench, and raises the quotas.
- Enterprise raises the limits further, on request.
- Hosting provider accounts, once VoxelBench has verified the provider, get limits of their own.
Paid plans are not on sale on the site yet: the Subscription tab of your account says when they open. The limits of each plan are detailed in Plans & Limits, API and Tokens and Auto-bench on the Website.
If You Are a Hosting Provider
Register your company, or claim the page VoxelBench may already have created for it in the hosting directory, then list your offers and request certifications. A certified report becomes public once you have approved it. The offers catalogue lists hosting plans side by side.