Configuration

Configuration

The config file is plugins/OptimizeServer/config.yml. After editing it, run /os reload.

Every value is checked on load. Invalid values are clamped to a safe range and a console message explains what changed. Older config versions are migrated automatically.

general

Key	Default	Description
enabled	true	Master switch
debug-logging	false	More detailed console logging
console-prefix	[OptimizeServer]	Prefix for console messages
telemetry-enabled	false	OptimizeServer never sends data to external endpoints, whatever this is set to
log-rotation.*	2048 KB × 10	Rotation settings for local logs

compatibility

Key	Default	Description
auto-detect-platform	true	Detects Paper, Folia, Purpur, and other platforms
force-safe-mode-on-unknown-platform	true	Unrecognised forks run in conservative safe mode
folia-region-safe-mode	true	Enforces Folia region-ownership rules
emit-compatibility-warnings	true	Logs compatibility notes on startup
strict-api-verification	true	Checks API methods exist before using them

monitoring

Sampling

Key	Default	Description
tick-sample-interval-ticks	1	Tick timing sample rate (1–20)
system-sample-interval-ticks	20	CPU/JVM snapshot rate (20 = 1 second)
world-sample-interval-ticks	100	Chunk/entity summary rate (100 = 5 seconds)
background-sample-interval-ms	5000	Async storage/task inspection interval

Thresholds. These decide when warnings and critical alerts appear:

Key	Default
thresholds.tps-warning / tps-critical	18.5 / 15.0
thresholds.mspt-warning / mspt-critical	40.0 / 50.0
thresholds.mspt-p95-warning / mspt-p99-critical	45.0 / 65.0
cpu.process-usage-warning-percent / critical	75 / 90
memory.heap-usage-warning-percent / critical	80 / 92
memory.gc-pause-warning-ms / critical	50 / 150
network.ping-warning-ms / critical	180 / 350
chunks.loaded-chunks-warning / critical	2500 / 5000
entities.total-entities-warning / critical	3000 / 6000
tasks.pending-tasks-warning	250
storage.free-space-warning-mb / critical	2048 / 512

memory.never-force-system-gc is always true.

optimization

Key	Default	Description
mode	HYBRID_CONDITIONAL	AUTOMATIC_SAFE, HYBRID_CONDITIONAL, MANUAL_ONLY, or SAFE_MODE
validate-before-activation	true	Each module is checked before it is turned on
auto-rollback-on-regression	true	A module is rolled back automatically if performance gets worse

Mode	Behaviour
AUTOMATIC_SAFE	Only the automatic-safe modules run
HYBRID_CONDITIONAL	Automatic-safe modules, plus conditional modules once they pass validation
MANUAL_ONLY	Nothing runs until an admin enables it
SAFE_MODE	Conservative mode with only the minimum needed for monitoring

See Diagnostics and Optimization for the module list.

safety

All disallow-* options and enforce-gameplay-invariants are locked to true. If you set one to false, it is set back to true and a console message tells you so. They exist in the file only to document the guarantees.

workers

Key	Default	Description
async-core-threads	2	Baseline async worker threads
async-max-threads	4	Maximum async worker threads
queue-capacity	256	Bounded task queue (stops memory from growing without limit)
keep-alive-seconds	60	How long an idle worker stays alive
shutdown-timeout-seconds	10	Time allowed for a clean shutdown

diagnostics & alerts

Key	Default	Description
diagnostics.min-confidence-threshold	0.55	Findings below this confidence are hidden
diagnostics.anomaly-zscore-threshold	2.5	How sensitive anomaly detection is
alerts.console-alerts-enabled	true	Logs alerts to the console
alerts.admin-permission-broadcast	false	Also sends alerts to online players with optimizeserver.admin
alerts.alert-cooldown-seconds	60	Minimum time between repeated alerts
alerts.min-severity	HIGH	Lowest severity that triggers an alert

reports

Key	Default	Description
directory	reports	Folder under plugins/OptimizeServer/
max-saved-reports	50	Oldest reports are deleted past this count
retention-days	14	Reports older than this are deleted
include-jvm-flags	true	Adds JVM arguments to reports

integrations

Key	Default	Description
auto-install.enabled	true	Downloads Spark/Chunky automatically if missing
auto-install.verify-sha512-checksum	true	Checks downloads before installing
spark.never-auto-upload	true	Profiles are never uploaded unless you choose to
chunky.never-auto-start-generation	true	Pre-generation only runs when started manually
chunky.safe-tps-floor-for-generation	18.0	Pre-generation is not recommended below this TPS
chunky.max-recommended-radius-blocks	5000	Upper limit for /os chunks recommend