Configuration

Learn how to configure HyperPerms for your server. This guide covers all configuration options and their effects.

Configuration File

The main configuration file is located at mods/com.hyperperms_HyperPerms/config.json. HyperPerms uses JSON format for all configuration files and automatically creates the config with sensible defaults on first run.

Full Configuration Reference

Here's the complete configuration file with all available options:

json

{
  "storage": {
    "type": "json"
  },
  "cache": {
    "enabled": true,
    "maxSize": 10000,
    "expireAfterAccessMinutes": 10
  },
  "defaultGroup": "default",
  "webEditor": {
    "enabled": true,
    "apiUrl": "https://api.hyperperms.com"
  },
  "analytics": {
    "enabled": false,
    "trackChecks": true,
    "trackChanges": true,
    "retentionDays": 90
  },
  "console": {
    "clickableLinksEnabled": true
  }
}

Configuration Sections

Storage Settings

json

"storage": {
  "type": "json"
}

type - Storage backend: json, sqlite, or mariadb

JSON storage works well for most servers. Use SQLite for analytics and audit logging, or MariaDB for larger servers with many players or when you need database-level reliability.

Cache Settings

json

"cache": {
  "enabled": true,
  "maxSize": 10000,
  "expireAfterAccessMinutes": 10
}

enabled - Enable permission result caching for performance
maxSize - Maximum number of cached permission results
expireAfterAccessMinutes - How long cached results are valid after last access (default: 10 minutes)

Keep caching enabled for best performance. The cache is automatically invalidated when permissions change.

Default Group

json

"defaultGroup": "default"

defaultGroup - The default group assigned to new players

Web Editor Settings

json

"webEditor": {
  "enabled": true,
  "apiUrl": "https://api.hyperperms.com"
}

enabled - Enable or disable the web editor integration
apiUrl - URL of the web editor API (default is the official HyperPerms API)

The web editor at hyperperms.com provides a visual interface for managing permissions. If you're self-hosting, update the API URL to your instance. See the self-hosting guide.

Analytics Settings

json

"analytics": {
  "enabled": false,
  "trackChecks": true,
  "trackChanges": true,
  "retentionDays": 90
}

enabled - Enable analytics tracking (requires SQLite JDBC driver)
trackChecks - Track permission check events
trackChanges - Track permission change events (grants, revocations, group changes)
retentionDays - How many days to keep analytics data before automatic cleanup

Analytics requires the SQLite JDBC driver. Download it from sqlite-jdbc releases and place it in mods/com.hyperperms_HyperPerms/lib/.

Console Settings

json

"console": {
  "clickableLinksEnabled": true
}

clickableLinksEnabled - Enable clickable links in console output (e.g., web editor URLs)

Reloading Configuration

After making changes to the configuration file, reload HyperPerms without restarting your server:

text

/hp reload

Some settings (like storage type) require a full server restart to take effect.

Example Configurations

Small Server (Under 50 Players)

json

{
  "storage": {
    "type": "json"
  },
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "expireAfterAccessMinutes": 10
  },
  "defaultGroup": "default",
  "webEditor": {
    "enabled": true,
    "apiUrl": "https://api.hyperperms.com"
  }
}

Large Server (100+ Players)

For large servers, we recommend MariaDB for its excellent performance and reliability across multi-server deployments. SQLite is also a great option for single-server setups.

json

{
  "storage": {
    "type": "mariadb"
  },
  "cache": {
    "enabled": true,
    "maxSize": 50000,
    "expireAfterAccessMinutes": 15
  },
  "defaultGroup": "default",
  "webEditor": {
    "enabled": true,
    "apiUrl": "https://api.hyperperms.com"
  },
  "analytics": {
    "enabled": true,
    "trackChecks": true,
    "trackChanges": true,
    "retentionDays": 30
  },
  "console": {
    "clickableLinksEnabled": true
  }
}

Next Steps

First Setup - Create your first groups and permissions
Storage Configuration - Deep dive into storage options
Self-Hosting the Web Editor - Run your own editor instance

Have questions or found an issue with the documentation?

Send us feedback →