> For the complete documentation index, see [llms.txt](https://docs.mantic.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mantic.dev/manticprotector/config-file-config.yml-or-mantic-dev.md).

# Config File (config.yml) | Mantic-Dev

Author: Jordan & Dejavu\
Support: <https://discord.mantic.dev>

Notes:

* All changes require a plugin reload or restart.
* Use placeholders (e.g., {player}, {uuid}, {realm}) where specified.
* Leave fields empty where indicated to use plugin defaults.

{% hint style="warning" %}
When enabled, debugMode prints detailed logs for troubleshooting. Disable in production to reduce console spam.
{% endhint %}

```yaml
# ===========================================
#
#         Mantic Protector Configuration
#
# -------------------------------------------
#
#   Author: Jordan & Dejavu
#   Support: https://discord.mantic.dev
#
#   Notes:
#    - All changes require a plugin reload or restart.
#    - Use placeholders (e.g., {player}, {uuid}, {realm}) where specified.
#    - Leave fields empty where indicated to use plugin defaults.
#
# ===========================================

# === License Key ===
# Plugin license key for authentication.
# You can obtain or manage your key at: https://discord.mantic.dev
license: "XXXX-XXXX-XXXX-XXXX"

# === Debug Mode ===
# When enabled, prints detailed logs for debugging.
# Useful for troubleshooting issues.
# ⚠ Disable in production to reduce console spam.
debugMode: false

# === Protected Users ===
# Players exempt from operator and permission checks.
# Useful for developers or trusted administrators.
# Format: username, UUID, allowed operator status, optional groups, IP, and geo history.
users:
  - username: "KingpinJordan"
    unique: "abed4eb2-02ba-4dfd-b33f-bf1e5f9137d0"
    allowedOp: true
    whitelistedGroups:
      - "Developer"
    addressHistory: []
    geoHistory: []
  - username: "TheDeejayV1"
    unique: "1a85be2f-e65b-4a05-a3f4-6f2ffd3696da"
    allowedOp: true
    whitelistedGroups:
      - "Developer"
    addressHistory: []
    geoHistory: []

# === Realm Name ===
# Represents the name of your server or network.
# Appears in Discord webhooks and plugin logs.
# If using LuckPerms, this value updates automatically.
realmName: "???"

# === General Plugin Settings ===
# Display name shown in plugin messages and logs.
# Keep it short and clean (avoid special characters).
#
# Leave this empty to use the plugin’s default internal name.
#
# ⚠ Changes require reload.
#
# ⚠ On Minecraft 1.17+ (Java 17+), name reflection may not update fully due to API restrictions.
pluginName: ""

# === Operator Checker ===
# Automatically checks for unauthorized operators.
opCheckerEveryXSeconds: 5

# Enable or disable the background operator check task.
opCheckerTask: false

# Commands executed when an unauthorized operator is detected.
# Use {player} as a placeholder for the player name.
notInListOpChecker:
  - "ban {player} Not Authorized to be opped! -s"

# === Console OP Protection ===
# Prevents the console from opping players not listed in the 'users' allowedOp list.
# Set to false to allow the console to op anyone.
canConsoleOpUnauthorizedUsers: true

# === Command Listener ===
# Monitors player commands for blocked words or unauthorized usage.
commandListener: true

# Permissions that trigger the blocked word scanner.
# Players using commands with these permissions will be checked for restricted terms.
commandWordWatcherPermissions:
  - "essentials.broadcast"
  - "worldedit.*"

# Commands executed when a player uses a blocked word.
# Use {player} as a placeholder.
commandsForBlockedWord:
  - "ban {player} Not Authorized to use this!"

# List of forbidden words in command usage.
# Players using these will trigger punishment commands.
blockedWords:
  - "hacked"
  - "griefed"

# === IP Protection ===
# Handles IP history and geolocation checks to detect suspicious logins.
ipHistory: true

# Enables IP geolocation lookups using the configured API.
ipGeolocation: true

# API endpoint or key for the IP geolocation service.
# Default: https://app.ipgeolocation.io/dashboard
apiKey: "https://app.ipgeolocation.io/dashboard"

# Algorithm used to hash and anonymize stored IP addresses.
# Recommended: SHA-256
hashAlgorithm: "SHA-256"

# === Unauthorized Operator Punishments ===
# Defines how staff and players are handled when unauthorized operator actions occur.
punishStaffWhoGaveOp: true

# Commands executed on staff who give operator to unauthorized players.
# Use {player} as a placeholder for the staff member.
staffPunishmentWhoGaveOp:
  - "deop {player}"
  - "ban {player} Not Authorized to give players op!"

# Commands executed on players who are opped without authorization.
# Use {player} as a placeholder.
unauthorizedOpUserPunishmentCmds:
  - "deop {player}"

# === Blocked Commands ===
# Commands players are not permitted to use.
blockedCommands:
  - "pl"
  - "plugins"
  - "version"
  - "op"

# === Blacklisted Groups ===
# Permission groups that are forbidden from being assigned.
blacklistedGroups:
  - "dev"
  - "owner"

# Commands executed when a player is found in a blacklisted group.
# Use {player} as a placeholder.
punishmentForBlacklistedGroups:
  - "lp user {player} clear"

# === Blacklisted Permissions ===
# Permissions that should never be assigned to players.
blacklistedPerms:
  - "essentials.*"
  - "*"
  - "bukkit.*"
  - "minecraft.*"
  - "worldedit.*"
  - "worldguard.*"
  - "luckperms.*"
  - "lp.*"
  - "luckperms.truseditor"
  - "luckperms.editor"
  - "luckperms.user.permission.set"
  - "excellentcrates.*"
  - "minecraft.admin"

# Enable permission blacklist checks on player join.
blacklistedPermsCheckJoin: true

# Commands executed on players with blacklisted permissions.
# Use {player} as a placeholder.
punishmentHasBlacklistedPerms:
  - "deop {player}"
  - "lp user {player} clear"

# === Punishment Listener ===
# Monitors mass punishment actions such as bans or kicks.
punishmentListener: false

# Types of punishments to track for mass punishment detection.
watchPunishmentTypes:
  - "ban"
  - "kick"

# Duration (in minutes) defining the tracking window for punishments.
storePunishmentWindowMinutes: 5

# If true, ignores silent punishments (e.g., with '-s' flag).
ignorePunishmentIfSilent: false

# Maximum number of punishments allowed within the defined time window.
maxPunishmentWithinWindow: 15

# Commands executed when the maximum punishment limit is exceeded.
# Use {player} as the punisher's name.
punishmentForMassPunishments:
  - "tempban {player} 6hr You have punished too many players within 5 minutes! -s"

# === Webhook Settings ===
# Discord webhook configuration for alerts and logging.
# Each webhook can be enabled or disabled individually.
# Use placeholders like {player}, {uuid}, {realm}, {ip}, {reason}.
opTaskAlertWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "**Player:** `{player}`"
    - "**UUID:** `{uuid}`"
    - ""
    - "**Reason:** `OP (TASK CHECKER)`"
    - ""
    - "**Realm:** `{realm}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false

joinBlacklistedPermWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "**Player:** `{player}`"
    - "**UUID:** `{uuid}`"
    - ""
    - "**Reason:** `Joined with blacklisted Permission {perm}`"
    - ""
    - "**Realm:** `{realm}`"
    - ""
    - "**IP:** `{ip}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false

blockedPlayerCommandOpWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "Player tried to op another player in-game!"
    - ""
    - "**Opper:** `{player}` (`{uuid}`)"
    - "**Victim:** `{victim}` (`{victim_uuid}`)"
    - ""
    - "**Realm:** `{realm}`"
    - "**Opper IP:** `{ip}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false

luckPermsWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "**Player:** `{player}`"
    - "**UUID:** `{uuid}`"
    - ""
    - "**Reason:** `{reason}`"
    - ""
    - "**Realm:** `{realm}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false

punishmentWatcherWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "**Player:** `{player}`"
    - "**UUID:** `{uuid}`"
    - ""
    - "**Punishments:** `{punishments}`"
    - ""
    - "**Realm:** `{realm}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false

ipMisMatchWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "**Player:** `{player}`"
    - "**UUID:** `{uuid}`"
    - ""
    - "**IP Hash:** `{ip-hash}`"
    - ""
    - "**Realm:** `{realm}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false

geoMisMatchWebhook:
  enabled: false
  webhookUrl: "https://discord.com/api/webhooks/XXXX/XXXX"
  webhookName: "Mantic Protector"
  webhookAvatar: "https://mantic.dev/logo.png"
  colour: "#1e90ff"
  title: ""
  description:
    - "**Player:** `{player}`"
    - "**UUID:** `{uuid}`"
    - ""
    - "**Geo Hash:** `{geo-hash}`"
    - ""
    - "**Realm:** `{realm}`"
  footer: "Made with ❤ by Jordan & Dejavu"
  mentionAll: false
```

Related:

* PreviousSetup Guide: <https://cozy-1.gitbook.io/cozy/setup-guide>

Last updated 3 days ago


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mantic.dev/manticprotector/config-file-config.yml-or-mantic-dev.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.