Configuration

/bench reload reloads the file. Most settings are read when they are used, so they apply to the next benchmark or test. A few are only read at startup and need a server restart: the language defaults, the rate-limit cooldown, update-check, hosting detection and the integrations. Remote monitoring is applied by /bench reload: it starts, stops or restarts with the new settings. The monitoring settings have their own /bench monitor reload (restart the web server afterwards), and custom profiles are re-read with /bench custom reload.

When VoxelBench updates, missing keys are added to your config.yml automatically. See Upgrading an Existing config.yml.

Language

language:
  default: en_US    # Default language, used when a player's language is not available
  force: false      # Force the default language for all players

• When force: false (default), VoxelBench automatically detects each player's Minecraft client language. Players can override it with /bench lang <code> and go back to detection with /bench lang auto.
• When force: true, all players see messages in the default language
• Bundled languages: en_US (English), fr_FR (French)

Language files are extracted to plugins/VoxelBench/lang/. You can edit them, and missing keys are filled in from the plugin on startup. VoxelBench also loads a translation file placed there for one of these codes: de_DE, es_ES, it_IT, pt_BR, ru_RU, zh_CN, ja_JP, ko_KR, pl_PL, nl_NL, tr_TR.

The web dashboard has its own translations (English and French), chosen from the browser language or the selector on the page.

Operating Mode

mode: anonymous    # anonymous or authenticated

Use /bench link to switch to authenticated mode. See Account Linking.

server-name: ""    # Name proposed for this server when linking it with /bench link

When server-name is empty, no name is sent during linking.

Notifications

notifications:
  sounds:
    enabled: true    # Play sounds on test/benchmark completion

Update Check

update-check: true

About 5 seconds after startup, VoxelBench asks voxelbench.com whether a newer version is available. If there is one, it is written to the console, and operators and players with voxelbench.admin are told in-game (also when they join). Set to false to disable the check.

Anonymization

Controls what data is included when reports are sent to voxelbench.com.

anonymous:
  anonymization-level: PARTIAL    # NONE, PARTIAL, or FULL

All levels always send: CPU name, RAM amount, Java version, OS name, and all benchmark metrics.

See Privacy & Security for more details.

Rate Limiting

rate-limiting:
  local-cooldown-minutes: 30    # Minutes between benchmarks

Prevents running benchmarks too frequently. Players with voxelbench.start.force permission can bypass this cooldown.

Benchmark Mode

benchmark-mode: standard    # standard or custom

The mode only changes what /bench start runs (see Benchmarks). Custom profiles and /bench test take their parameters from the profile or the command line.

Custom Test Parameters

The tests: section and the counts of benchmark-tests: are used by /bench start when benchmark-mode: custom:

tests:
  single-core-benchmark:
    duration: 10                # Measurement duration in seconds
  multi-core:
    threads: 100
    iterations: 100000
    limits:                     # Bounds for /bench test multiCore
      threads-min: 1
      threads-max: 200
      iterations-min: 1000
      iterations-max: 1000000
  disk:
    threads: 4
    queue-depth: 8
    file-size-mb: 512
    random-4k-operations: 200   # In thousands (200 = 200,000 operations)
    passes: 3
    limits:                     # Bounds for /bench test disk
      size-min-mb: 64
      size-max-mb: 4096
      threads-min: 1
      threads-max: 32
      queue-depth-min: 1
      queue-depth-max: 64
      passes-min: 1
      passes-max: 20
  memory:
    size-mb: 512
    iterations: 75000
    runs: 3
    limits:                     # Bounds for /bench test memory
      size-min-mb: 16
      size-max-mb: 1024
      passes-min: 1
      passes-max: 10
  block-physics:
    count: 24000                # Falling blocks
    interval-ticks: 1           # Ticks between two spawn waves

benchmark-tests:
  chunk-loading:
    chunks-to-load: 200
    limits: { min: 10, max: 5000 }
    adaptive:                   # Chunk-loading throttle (/bench test, custom mode, custom profiles)
      window-max: 200
      target-mspt-ms: 75.0
      soft-cap-mspt-ms: 100.0
      critical-mspt-ms: 250.0
  mob-spawn:
    mob-count: 300
    duration-seconds: 30
    limits: { min: 10, max: 1000 }
  hopper:
    hopper-chain-length: 50
    parallel-lines: 1
    limits: { min: 1, max: 10 }
  explosion:
    tnt-count: 30
    raise-host-tnt-quota: true
    limits: { min: 1, max: 200 }
  dispersed-zones:
    default: 8
    limits:
      min: 1
      max: 10

A few of these settings are not limited to custom mode:

• chunk-loading.adaptive controls how fast a chunk loading run pushes chunk generation: the per-tick budget grows while MSPT stays under target-mspt-ms, backs off above soft-cap-mspt-ms and drops to one chunk per tick above critical-mspt-ms. Keep the defaults unless you know why you change them.
• explosion.raise-host-tnt-quota: true raises Spigot's max-tnt-per-tick in memory for the duration of an explosion test, then restores it (spigot.yml is never written). With false, the host limit is left alone and a run whose charges could not all tick is reported as a partial measurement.
• hopper.hopper-chain-length and mob-spawn.duration-seconds apply to hopper and mob spawn tests outside the standard benchmark (stress limit sets its own chain length).
• The limits of chunk-loading, mob-spawn and explosion cap the count these tests receive in /bench test, benchmark-mode: custom and custom profiles. They are read at each run, so /bench reload is enough to apply a new bound.
• The limits of hopper only bound /bench test hopper <lines>. A custom profile runs the number of lines it asks for, up to 500 per zone, whatever these limits say (see Custom Profiles).
• mob-pathfinding, redstone and block-physics have no limits block: /bench test validates their arguments against fixed ranges, printed in the error message when a value is out of range.
• The standard /bench start ignores all of the above (limits, adaptive, hopper-chain-length, dispersed-zones.limits): it always runs the same fixed load — 10 hopper lines × 50, 150 TNT, 2000 chunks per zone with the default throttle, 8 zones — so a standard score measures the same thing on every server. Only explosion.raise-host-tnt-quota still applies, because it is a permission to touch the host's settings, not a load setting.
• Every chunk loading run stays under a memory ceiling that no setting changes: 30 % of the maximum heap, counted at about 50 KB per chunk, shared by the zones the test walks, and never cut below 200 chunks per zone. With 8 zones, a zone gets at most 0.75 chunk per MB of maximum heap, so the standard 2000 chunks per zone need a maximum heap of about 2,670 MB; on a smaller heap, the standard benchmark loads fewer.

Dispersed Zones

dispersed-zones.default is the number of test zones, spread far apart in the benchmark world, that the multi-zone tests use in benchmark-mode: custom. It is kept within limits and always between 1 and 10. The standard benchmark and custom profiles always use 8 zones, whatever this value, so their results stay comparable.

Benchmark Runs

All benchmark: settings live in a single block:

benchmark:
  target-world: ""           # Pinned world, set with /bench world set
  auto-temp-world: true      # Create a temporary flat world when no world is pinned

  post-cleanup-gc: true      # Full GC after each test's cleanup

  memory-budget:             # Checked before each test
    enabled: true
    warn-pct: 75.0
    fail-pct: 85.0

  memory-watchdog:           # Watches the heap during each test
    enabled: true
    critical-pct: 92.0
    hold-seconds: 3

• target-world: the world used by every benchmark, test and stress run. Set it with /bench world set <name> and clear it with /bench world unset. If the pinned world is not loaded, VoxelBench warns and ignores the pin.
• auto-temp-world: when no world is pinned, /bench start, /bench stresslimit, /bench tier and custom profiles create a temporary flat world named voxelbench_temp_<timestamp>, run in it and delete it at the end (the world is also imported into Multiverse-Core when it is installed). A custom benchmark profile can only turn it off for its own runs, with options.auto-temp-world: false: true in a profile creates no temporary world when this setting is false (see Custom Profiles). With false, these runs use the server's main world, and the pre-flight check of /bench start reports a critical "No target world configured" finding. /bench test applies it differently. A test that writes to the world (every gameplay test except worldSave) never runs in the world you are in: it uses the pinned world, otherwise a temporary world, and with auto-temp-world: false it is refused. On Folia, which cannot create a world while running, such a test needs a pinned world. The hardware and CPU tests and worldSave use the pinned world, or the world you are in (see Benchmarks).
• post-cleanup-gc: forces a full garbage collection after each test's cleanup, so the memory left by one test does not weigh on the next one.
• memory-budget: before each test, VoxelBench estimates the heap usage the test will reach. From warn-pct percent of the maximum heap, it runs a garbage collection first; if the estimate is still at or above fail-pct percent afterwards, the test is skipped and reported as such instead of risking an out-of-memory crash.
• memory-watchdog: during a test, if heap usage stays at or above critical-pct percent for hold-seconds consecutive seconds, the test is aborted and reported as skipped.

Keep all these keys under one benchmark: block: if a YAML file declares the same top-level key twice, only the last block is kept.

Confirmation

confirmation:
  require-confirmation: true    # Run pre-flight checks before /bench start
  popup: true                   # Yes/No window after a preview that waits for "confirm"

/bench start has no confirmation command. When require-confirmation is true (default), /bench start first runs the pre-flight checks:

• If nothing is found, the benchmark starts immediately.
• Otherwise an inventory screen lists the findings (world not flat, other players online, server already under load, free hosting, plugins likely to interfere...). Click Start benchmark to launch it or Cancel to abort.
• When a finding is critical (for example, the target world is not a voxelbench_* world), the normal start button is disabled. Only a player with voxelbench.start.force gets a Force start button.

When set to false, /bench start skips the pre-flight checks and starts right away.

This option only affects /bench start. /bench stresslimit always asks you to type the command a second time within 10 seconds, and /bench tier and /bench custom run start without confirmation.

popup concerns the commands that show a preview and wait for confirm: a heap dump, and upload/share … preview for profiles and memory reports. When true (default), a player also gets a Yes/No window with the preview — a native dialog on Paper 1.21.6 and later, an inventory screen elsewhere — whose Yes runs the … confirm command itself, with all its checks. When false, only the clickable line in chat and /bench confirm remain. Read at each preview: /bench reload is enough. See Confirming a Preview.

Hosting Detection

hosting-detection:
  enabled: true     # Detect the hosting environment at startup
  silent: false

At startup, VoxelBench looks for signs of a free or shared hosting environment (for example Aternos, Minehut, or a hosting panel with little memory) and classifies the server, from DEDICATED_OR_VPS to CONFIRMED_FREE. The result is logged, and when a free tier is likely:

• a warning with the reasons is written to the startup log
• the pre-flight checks of /bench start show a "Free-tier hosting detected" finding, pointing to the lighter free-host profile
• the report's hostingEnvironment block carries the detected tier, provider and signals, so voxelbench.com can tell these runs apart

silent: true records the warning as not shown (warningEmitted: false) in reports; it does not hide the startup log warning or the pre-flight finding. With enabled: false, no detection runs. Changes need a restart.

Stress Limit

stress-limit:
  warm-start:
    enabled: true                # false = always climb from the starting load
    factor: 0.70                 # start at 70% of the last stable value
    max-refine-down-steps: 6     # binary steps when the warm probe breaks
    max-age-days: 30             # ignore remembered values older than this

After each full stress limit run, VoxelBench remembers the last stable load of each stress type in plugins/VoxelBench/stress-warmstart.yml. With warm start enabled, the next run starts at factor times that value instead of climbing from the starting load. If that first tier breaks, it searches downwards for at most max-refine-down-steps steps, then restarts from the starting load if nothing holds. /bench tier ... cold ignores the warm start for one run. See Stress Limit.

The other stress limit settings (thresholds, ramp, tier duration) are not in config.yml: they are fixed for the official run and can be changed in a custom stress profile.

Logging

logging:
  test-verbosity: NORMAL    # MINIMAL, NORMAL, VERBOSE, DEBUG
  log-test-results: true    # Log result summary for each test
  log-benchmark-progress: true    # Log which test is running

These settings are applied by /bench reload.

benchmark-diagnostics: false

Troubleshooting aid for benchmark runs: when true, VoxelBench counts entities, dropped items, mobs and loaded chunks in every world before and after each test and warns when a test's cleanup left something behind. The counts themselves are logged at VERBOSE verbosity.

Monitoring

See Monitoring for how each feature works. Apply changes with /bench monitor reload, then restart the web server (/bench monitor web stop, then start).

monitor:
  web-port: 8080                 # HTTP port of the dashboard and /api/metrics
  bind-address: "127.0.0.1"      # This machine only; any other address requires a password

  https:
    enabled: false               # Serve over HTTPS on https.port instead of web-port
    port: 8443
    keystore-path: "certificates/keystore.jks"   # Relative to plugins/VoxelBench/
    keystore-password: ""        # Set by /bench monitor https generate
    key-alias: "voxelbench"

  auto-start:                    # Start services when the server starts
    web-server: false
    push-service: false
    boss-bars: false             # TPS + MSPT boss bars (see Monitoring for who sees them)

  dashboard:
    enabled: true                # false = /api/metrics only, no HTML page

  auth:
    enabled: false
    username: "admin"
    password-hash: ""            # Set from the console: /bench monitor auth password <password> (12+ characters)
    password-salt: ""
    session-timeout: 60          # Minutes
    api-key: ""                  # Set with /bench monitor auth key pull

  behind-proxy: false            # true only behind a trusted reverse proxy (reads X-Forwarded-For)

  whitelist:
    enabled: false
    mode: "all"                  # all, dashboard or api
    allowed-ips:
      - "127.0.0.1"
      - "::1"
    denied-message: "Access denied: Your IP is not whitelisted"

  push:
    enabled: false               # Displayed in the GUI; push starts with /bench monitor push start or auto-start
    url: ""                      # Destination of the POST requests
    api-key: ""                  # Sent as "Authorization: Bearer"; /bench monitor auth key push
    interval-seconds: 1
    allow-insecure: false        # Accept unverified TLS certificates

Never set behind-proxy: true on a dashboard exposed directly to the internet: any client could then forge its IP address and get past the whitelist.

Reports

See Reports for details.

reports:
  enabled: true          # false disables local reports and /bench reports
  folder: "reports"      # Relative to plugins/VoxelBench/

  backend:
    unit-tests: false    # Send /bench test and /bench tier results (requires /bench link)

  retention:             # -1 = unlimited
    max-age-days: 90     # Delete reports older than 90 days
    max-per-type: 100    # Max reports per type
    max-total: 500       # Max total reports
    cleanup-on-startup: true

  storage:               # Which report types are saved locally
    unit-tests: true     # /bench test
    benchmarks: true     # /bench start
    stresslimit: true    # /bench stresslimit, /bench tier, stress profiles

Full benchmarks and stress limit runs are submitted to voxelbench.com regardless of these settings (a custom profile only with submit: true in the profile); reports.backend.unit-tests only controls individual test results. These settings only decide what is written to disk: a run whose type is disabled here leaves no local report at all.

Remote Monitoring

Remote monitoring sends periodic metric snapshots and detected events to your server's dashboard on voxelbench.com. It requires a linked server.

The simplest way to turn it on is /bench monitor remote on: it sets enabled: true, starts the service and checks the connection right away, telling you in game what is left to do. Editing the file works too: set enabled: true and run /bench reload. /bench monitor remote status shows where it stands (link, service, last check-in, last upload).

Monitoring must also be enabled for the server on voxelbench.com (Monitoring page of your dashboard), and your plan must include it. The order does not matter: while the site refuses the data, the plugin pauses and checks again on its own (every minute, or every 10 minutes when the plan does not include monitoring), then starts sending as soon as the site accepts. It never turns itself off in config.yml. If the site no longer recognises the link, the service stops until you run /bench link again.

remote-monitoring:
  enabled: false
  collect-interval: 60    # Seconds between two snapshots (30 - 600)
  send-interval: 60       # Seconds between two uploads of buffered snapshots (60 - 3600)
  buffer-size: 120        # Snapshots kept in memory before the oldest are dropped (10 - 1000)
  folia-regions:
    max-detailed: 64      # Folia only: regions listed one by one per snapshot, worst first (0 - 256)

On Folia, each snapshot measures every region and lists up to folia-regions.max-detailed of them, worst first, with their coordinates, TPS and tick times (about 200 bytes each); the others are only counted, and the worst and average values still cover them all. 0 sends the worst and average values only. Paper and Spigot ignore it. See Monitoring.

Both intervals are real time: a lagging server keeps its pace. TPS, MSPT, memory, CPU and GC are read off the main thread; players, entities, chunks and worlds are read on the main thread at the same pace and left out of a snapshot when that reading is too old. A backlog is uploaded in several batches of 60 snapshots, and snapshots older than about two hours are dropped, since voxelbench.com refuses them. When the server stops, the last snapshots are sent before it shuts down. Upgrading from 1.9.0 or earlier changes a send-interval still at the former default of 300 to 60: voxelbench.com evaluates alert rules every minute on the data it has received. Any other value is kept. A collect-interval below 30 is raised to 30: below that, voxelbench.com's per-plan point budget refuses snapshots after a few hours, and each snapshot already reports the worst tick of its interval.

Events

Event detection runs while remote monitoring runs. Each event has its own enabled switch; cooldown-seconds is the minimum delay between two events of the same kind.

remote-monitoring:
  events:
    enabled: true

    performance:
      tps-drop:                # TPS below threshold for at least duration-seconds
        enabled: true
        threshold: 18.0
        duration-seconds: 10
        cooldown-seconds: 60
      tps-critical:            # TPS below threshold, reported immediately
        enabled: true
        threshold: 10.0
        cooldown-seconds: 120
      tps-recovery:            # Sent when a sustained drop ends
        enabled: true
      gc-major:                # Major (old-gen / full-heap) GC pauses in a 5-second sample
        enabled: true
        threshold-ms: 200
        cooldown-seconds: 30

    memory:                    # percent = heap used / maximum heap
      high:
        enabled: true
        percent: 80
        cooldown-seconds: 300
      critical:
        enabled: true
        percent: 95
        cooldown-seconds: 120

    security:
      op-changes:
        enabled: true
      config-reload:           # Sent on /bench reload
        enabled: true
      whitelist-changes:
        enabled: true
      check-interval: 30       # Seconds between two checks of the op list and whitelist (5 - 3600)

    player:                    # percent = share of the server's player slots
      high:
        enabled: true
        percent: 80
        cooldown-seconds: 300
      full:
        enabled: true
        cooldown-seconds: 300

    litebans:                  # Requires LiteBans; takes effect at the next restart
      enabled: false           # Off by default: sanctions name players
      bans: true
      mutes: true
      kicks: true
      include-reason: false    # Also send the reason typed by the staff member

• TPS and GC are sampled every 5 seconds, memory every 15 seconds.
• tps-recovery uses the tps-drop threshold and cooldown.
• The LiteBans events forward bans, mutes and kicks (and their reversal) with the player and the operator, and the reason only with include-reason: true; see Integrations. New installations have them off; an existing config.yml keeps its enabled value.
• A missing key behaves like the default value shown here.

Profiling (experimental)

Settings of /bench profile, see Profiling. Out-of-range values are clamped to the bounds shown.

profiling:
  enabled: true                  # false: every /bench profile action is refused
  ring:
    enabled-on-start: false      # start the ring buffer with the server (opt-in)
    period-ms: 20                # 10-100
    max-age-seconds: 300         # 60-3600
    max-size-mb: 32              # 4-512, in JFR's repository (JVM temp directory)
  auto-dump:
    enabled: true                # only while the ring buffer runs
    slow-tick-ms: 100            # 55-10000
    consecutive-slow-ticks: 40   # 1-1200
    freeze-ms: 1000              # at least slow-tick-ms, at most 60000
    cooldown-seconds: 300        # 30-86400
  storage:
    max-files: 20                # 1-500
    max-total-mb: 100            # 1-10240
    keep-raw-jfr: false          # also keep the raw .jfr next to each JSON
  upload:
    enabled: true                # false: /bench profile upload is refused
    max-size-kb: 1024            # 64-4096, uncompressed JSON
  share:
    enabled: true                # false: /bench profile share is refused (unshare still works)
    max-size-kb: 1024            # 64-4096, uncompressed cleaned copy

/bench reload applies the automatic dump thresholds and the retention limits at once; the ring buffer settings apply the next time it starts (/bench profile ring off, then on).

Memory Inspection (experimental)

Settings of /bench memory, see Memory Inspection. Out-of-range values are clamped to the bounds shown; every change applies at the next command (no reload needed).

memory-inspection:
  enabled: true                  # false: every /bench memory action is refused
  summary:
    max-files: 20                # 1-500
    max-total-mb: 20             # 1-1024
  host-disk-limit-gb: 0          # 0-1048576 (0: none or unknown)
  dump:
    enabled: true                # false: /bench memory dump is refused
    max-files: 2                 # 1-10
    min-free-disk-mb: 1024       # 0-1048576
  analysis:
    enabled: true                # false: /bench memory analyze is refused
    max-heap-mb: 4096            # 256-65536
    disk: true                   # false: the full analysis never keeps its graph on disk
    memory-margin-mb: 512        # 0-65536
    timeout-seconds: 1800        # 60-7200
    cpu-throttle:
      max-cores: 2               # 0-256 (0: never throttled)
      percent: 30                # 5-100
    max-files: 20                # 1-500
    max-total-mb: 20             # 1-1024
  upload:
    enabled: true                # false: /bench memory upload is refused
    max-size-kb: 1024            # 64-4096
  share:
    enabled: true                # false: /bench memory share is refused (unshare still works)
    max-size-kb: 1024            # 64-4096

Upgrading an Existing config.yml

On startup, VoxelBench adds the keys introduced by a new version to your config.yml without touching your values, then applies one-time migrations recorded by config-version (do not edit that key).

• Duplicate benchmark: block. Older bundled files declared benchmark: twice. YAML only keeps the last block, so anything written in the first one (typically target-world and auto-temp-world) was silently ignored. When VoxelBench finds a top-level key declared more than once, it logs a warning and rewrites the file with a single block. The values that sat in the ignored block are not recovered: set them again (for example with /bench world set).
• config-version 9. benchmark-tests.dispersed-zones.default used to be ignored (every run used 8 zones). A default: 1 left from an older file is rewritten to 8; any other value is kept and is now applied in custom mode.
• Keys no longer used. These keys were never read and have been removed from the bundled file; you can delete them from yours: tests.single-core.*, tests.network.test-servers, benchmark-tests.chunk-loading.radius, benchmark-tests.hopper.items, benchmark-tests.world-save, the whole benchmark-tests.mob-pathfinding, benchmark-tests.redstone and benchmark-tests.block-physics blocks (count, duration and limits), and reports.auto-show-report.
• Keys added. update-check, server-name, benchmark-diagnostics, tests.single-core-benchmark.duration, tests.disk.random-4k-operations, tests.disk.passes, tests.block-physics.count and tests.block-physics.interval-ticks.

Integrations

See Integrations for the complete integrations configuration reference.

integrations:
  dynmap:
    enabled: true
  spark:
    enabled: true
  discordsrv:
    enabled: true
    channel-id: ""