AegisPerms

A command firewall for dedicated Fabric servers. For every player and every node of the command tree, AegisPerms decides what is seen and what can be used: vanilla commands and the commands of other mods, sub-commands and arguments included, without those mods having to cooperate, and with nothing to install on the client.

A word before you start.

AegisPerms comes from a long line: GhuPerms in 2023, a prototype in 2025, and this rewrite in 2026, specified before a single line of code. On the code and the documentation: I do not enjoy writing markdown, and this time the code too was written with the help of an AI, which I steered, reviewed and tested on real servers; Modrinth's AI-generated content disclosure is there for that reason.

If something is unclear or wrong, open an issue. I hope it serves you well.

What it does

• Weighted groups that inherit from each other, per-player rules, and a server closed by default: a newcomer only gets what the default group opens, and vanilla decides wherever no rule speaks.
• Keys derived from the command tree, such as minecraft:command.teleport.targets.location, and a catalog that lists them all, vanilla requirement included: nothing to declare, nothing to guess.
• Seeing and using kept apart: a refusal hides the command, or leaves it visible with a message, your choice.
• Prefixed forms and aliases the vanilla client understands, completion and colours included: /mc:teleport, /gm for /gamemode.
• /aegis why explains a decision node by node, and /aegis check gives the decision for one key, with the rule that wins.
• Two JSON files, edited by hand or through /aegis, validated with the line of each error, reloaded without a command, backed up and restored.
• An observe mode that computes and logs decisions without applying them, while you tune the rules on a live server.
• A provider for both permission APIs, the Fabric API one and Lucko's, so that other mods follow the same groups.

Who it is for

The administrator of a dedicated Fabric server, small or medium: friends, a community, a modded server, a test server. You want to open an op command to a player without making them op, remove a single sub-command, keep your moderators at a low op level and open them, command by command, what you choose, know why a command is refused, and keep your rules in files you can read, version and copy from one server to another.

Getting started

Drop the jar for your game version into the server's mods folder, next to the Fabric API and Fabric Language Kotlin. Everything else ships inside the jar. On first start the mod writes config/aegisperms/settings.json and permissions.json with two groups: default, which refuses every command except /help, /me and /msg, and admin, which opens everything to level 4 operators. A player then only sees /mc:help, /mc:me and /mc:msg; a level 4 operator sees everything, plus /aegis. The console and RCON are never judged.

/aegis group vip create 80
/aegis group vip allow minecraft:command.teleport
/aegis player Joe group add vip
/aegis why Joe mc:teleport Joe 10 64 10

Joe can teleport, and why tells why, node by node.

Keys and groups

A key names a node of the command tree: minecraft:command.teleport is /teleport, minecraft:command.teleport.targets.location is its <targets> <location> form, command is every command at once. A rule on a key covers everything below it. The mod reads the keys from the tree of your server, vanilla and mods alike, and writes them all to catalog.json with their vanilla requirement: you never have to guess a key, and /aegis catalog lists them.

Groups have a weight and parents. A player's own rules speak first, then the groups, heaviest first; the first set that has a rule for the key decides, and the most precise rule of that set wins. Operators join groups ex officio by op level, so admin keeps every op of level 4 in charge. Without any rule, vanilla decides, exactly as before the mod.

A refusal closes the whole branch. No allow placed deeper reopens a sub-tree that a rule above has closed, and no alias or prefixed form goes around a refusal: they lead to the same key as the command they name.

Seeing and using

A refused command can be hidden, the default: it disappears from the client's completion and answers "Unknown command", as if it did not exist. Or it can stay visible, per rule or by a global setting: the player sees it, types it, and the gate answers a message instead of running it. /aegis itself always stays with the administrators, whatever the rules say.

Prefixed forms and aliases

Every root command receives a form prefixed by its mod, /mc:teleport for vanilla, /<modid>:home for a mod. With require-prefix, on by default, a judged player only sees the prefixed forms, one per command, while the console, data packs and other mods keep the bare names. Aliases are yours to define in settings.json: "gm": "minecraft:gamemode" gives /gm, "wla": "minecraft:whitelist add" gives /wla <player>. Forms and aliases are real nodes of the tree: the vanilla client completes and colours them like any command.

Explaining a decision

/aegis why <player> <command line> does what the server would do if the player typed the line, and tells it node by node: the status of each node, the decision, the rule that wins and where it comes from, the sets that were set aside, then the verdict. /aegis check <player> <key> answers for a single key. Both work for players online or offline, and change nothing.

The files

settings.json holds the settings: the mode, the admin level, the namespaces and prefixes, the aliases, the language, the watch. permissions.json holds the groups and the players. Both are validated as a whole at every read, with the file, the JSON path and the line of each error; an invalid file never applies, the running state stays, and the server never starts open by accident: it falls back on the last good copy, then on the shipped files, and tells the operators. A file edited by hand reloads within two seconds, or with /aegis reload; /aegis backup and /aegis restore copy and bring back both files.

Observe mode

Set "mode": "observe" before the first start on a living server, or type /aegis mode observe: the mod computes its decisions and logs every difference with what vanilla does, without applying anything. Players keep what vanilla gives them, why and check say what would happen, and you switch to enforce when the rules are right.

Permission APIs

AegisPerms answers the permission API of the Fabric API and Lucko's fabric-permissions-api, embedded in the jar: a mod that asks for homes:home/limit gets the decision of the same groups, true, false, or nothing to let the mod use its own fallback. Every key a mod asks for enters the catalog, so you can write a rule on it.

Compatibility

AegisPerms is the only permission manager of its server. It refuses to start next to LuckPerms, Vanilla Permissions, Universal Perms or Player Roles, and the loader names both mods before the game loads. It never touches ops.json, never judges the console or RCON, and leaves vanilla the powers that an op level gives outside commands.

Documentation

The documentation lives in the repository, github.com/Roumoulou/AegisPerms, and is written in French: getting started, the model for LuckPerms users, the /aegis reference, the files, troubleshooting, plus the technical documentation and the specification. Bugs and questions go to the issue tracker. Licence: LGPL-3.0-only.

Requirements

Minecraft 26.3, 26.2 or 26.1.2, one jar per version: take the one for your game. A dedicated server: the mod is server-side only, a client that finds it in its mods folder does not load it, and players have nothing to install. Fabric Loader 0.19.5 or newer, Fabric Language Kotlin 1.14.1 or newer, and the Fabric API of your version: 0.163.0 or newer for 26.3, 0.161.0 for 26.2, 0.155.3 for 26.1.2. Java 25.

---

AegisPerms (français)

Le pare-feu des commandes d'un serveur Fabric dédié. Pour chaque joueur et pour chaque nœud de l'arbre des commandes, AegisPerms décide ce qui se voit et ce qui s'utilise : les commandes de vanilla et celles des autres mods, sous-commandes et arguments compris, sans que ces mods aient à coopérer et sans rien installer côté client.

Un mot avant de commencer.

AegisPerms vient de loin : GhuPerms en 2023, un prototype en 2025, et cette réécriture en 2026, spécifiée avant la première ligne de code. Sur le code et la documentation : je n'aime pas écrire du markdown, et cette fois le code aussi a été écrit avec l'aide d'une IA, que j'ai dirigée, relue et éprouvée sur de vrais serveurs ; la mention de contenu généré par IA de Modrinth est là pour cette raison.

Si quelque chose est obscur ou faux, ouvrez un ticket. J'espère qu'il vous servira.

Ce que fait le mod

• Des groupes pondérés qui héritent les uns des autres, des règles propres à un joueur, et un serveur fermé par défaut : un nouveau venu n'a que ce que le groupe default ouvre, et vanilla décide partout où aucune règle ne parle.
• Des clés déduites de l'arbre des commandes, minecraft:command.teleport.targets.location, et un catalogue qui les liste toutes, exigence vanilla comprise : rien à déclarer, rien à deviner.
• Voir et utiliser distingués : un refus masque la commande, ou la laisse visible avec un message, au choix.
• Les formes préfixées et les alias que le client vanilla comprend, complétion et couleurs comprises : /mc:teleport, /gm pour /gamemode.
• /aegis why, qui explique une décision nœud par nœud, et /aegis check, qui donne la décision d'une clé avec la règle qui l'emporte.
• Deux fichiers JSON édités à la main ou par /aegis, validés avec la ligne de l'erreur, rechargés sans commande, sauvegardés et restaurés.
• Un mode observation, qui calcule et journalise les décisions sans les appliquer, le temps d'ajuster les règles sur un serveur vivant.
• Un fournisseur des deux API de permissions, celle de la Fabric API et celle de lucko, pour que les autres mods suivent les mêmes groupes.

Pour qui

L'administrateur d'un serveur Fabric dédié, petit ou moyen : entre amis, une communauté, un serveur moddé, un serveur de test. Vous voulez ouvrir une commande d'op à un joueur sans le rendre op, retirer une seule sous-commande, tenir vos modérateurs à un niveau d'op bas et leur ouvrir, commande par commande, ce que vous voulez, savoir pourquoi une commande est refusée, et garder vos règles dans des fichiers que vous lisez, versionnez et copiez d'un serveur à l'autre.

Pour commencer

Posez le jar de votre version dans mods du serveur, avec la Fabric API et Fabric Language Kotlin. Le mod embarque le reste. Au premier démarrage, il écrit config/aegisperms/settings.json et permissions.json avec deux groupes : default, qui refuse toute commande sauf /help, /me et /msg, et admin, qui ouvre tout aux ops de niveau 4. Un joueur ne voit alors que /mc:help, /mc:me et /mc:msg ; un op de niveau 4 voit tout, et /aegis. La console et le RCON ne sont jamais jugés.

/aegis group vip create 80
/aegis group vip allow minecraft:command.teleport
/aegis player Joe group add vip
/aegis why Joe mc:teleport Joe 10 64 10

Joe se téléporte, et why raconte pourquoi, nœud par nœud.

Les clés et les groupes

Une clé nomme un nœud de l'arbre des commandes : minecraft:command.teleport est /teleport, minecraft:command.teleport.targets.location sa forme <targets> <location>, command toutes les commandes à la fois. Une règle sur une clé couvre tout ce qui descend d'elle. Le mod lit les clés dans l'arbre de votre serveur, vanilla et mods confondus, et les écrit toutes dans catalog.json avec leur exigence vanilla : vous n'avez jamais à deviner une clé, et /aegis catalog les liste.

Les groupes ont un poids et des parents. Les règles propres d'un joueur parlent d'abord, puis les groupes, du plus lourd au plus léger ; le premier ensemble qui a une règle pour la clé décide, et la règle la plus précise de cet ensemble l'emporte. Les ops entrent d'office dans des groupes par niveau d'op, si bien qu'admin garde tout op de niveau 4 aux commandes. Sans aucune règle, vanilla décide, exactement comme avant le mod.

Un refus ferme toute la branche. Aucun allow posé plus bas ne rouvre un sous-arbre qu'une règle au-dessus a fermé, et aucun alias ni aucune forme préfixée ne contourne un refus : ils mènent à la même clé que la commande qu'ils nomment.

Voir et utiliser

Une commande refusée peut être masquée, le défaut : elle disparaît de la complétion du client et répond « commande inconnue », comme si elle n'existait pas. Ou rester visible, règle par règle ou par un réglage global : le joueur la voit, la tape, et la porte répond un message au lieu de l'exécuter. /aegis reste toujours aux administrateurs, quoi que disent les règles.

Les formes préfixées et les alias

Chaque commande racine reçoit une forme préfixée par son mod, /mc:teleport pour vanilla, /<modid>:home pour un mod. Avec require-prefix, actif par défaut, un joueur jugé ne voit que les formes préfixées, une par commande, tandis que la console, les datapacks et les autres mods gardent les noms nus. Les alias sont à vous, dans settings.json : "gm": "minecraft:gamemode" donne /gm, "wla": "minecraft:whitelist add" donne /wla <joueur>. Formes et alias sont de vrais nœuds de l'arbre : le client vanilla les complète et les colore comme toute commande.

Expliquer une décision

/aegis why <joueur> <ligne de commande> fait ce que le serveur ferait si le joueur tapait la ligne, et le raconte nœud par nœud : le statut de chaque nœud, la décision, la règle qui l'emporte et d'où elle vient, les ensembles écartés, puis le verdict. /aegis check <joueur> <clé> répond pour une seule clé. Les deux marchent pour un joueur en ligne ou hors ligne, et ne changent rien.

Les fichiers

settings.json porte les réglages : le mode, le niveau d'administration, les espaces de noms et les préfixes, les alias, la langue, la surveillance. permissions.json porte les groupes et les joueurs. Les deux sont validés ensemble à chaque lecture, avec le fichier, le chemin JSON et la ligne de chaque erreur ; un fichier invalide ne s'applique jamais, l'état en vigueur reste, et le serveur ne démarre jamais ouvert par accident : il se replie sur la dernière bonne copie, puis sur les fichiers livrés, et le dit aux opérateurs. Un fichier édité à la main se recharge en deux secondes, ou par /aegis reload ; /aegis backup et /aegis restore copient et ramènent les deux fichiers.

Le mode observation

Écrivez "mode": "observe" avant le premier démarrage sur un serveur vivant, ou tapez /aegis mode observe : le mod calcule ses décisions et journalise chaque écart avec ce que fait vanilla, sans rien appliquer. Les joueurs gardent ce que vanilla leur donne, why et check disent ce qui se passerait, et vous passez en enforce quand les règles sont justes.

Les API de permissions

AegisPerms répond à l'API de permissions de la Fabric API et à la fabric-permissions-api de lucko, embarquée dans le jar : un mod qui demande homes:home/limit reçoit la décision des mêmes groupes, true, false, ou rien, pour laisser le mod à son propre repli. Chaque clé qu'un mod demande entre au catalogue, et vous pouvez écrire une règle dessus.

Compatibilité

AegisPerms est seul maître des droits sur son serveur : il refuse de démarrer avec LuckPerms, Vanilla Permissions, Universal Perms ou Player Roles, et le chargeur nomme les deux mods avant que le jeu ne charge. Il ne touche jamais à ops.json, ne juge jamais la console ni le RCON, et laisse à vanilla les pouvoirs qu'un niveau d'op donne hors des commandes.

Documentation

La documentation vit dans le dépôt, github.com/Roumoulou/AegisPerms, en français : la prise en main, le modèle pour qui vient de LuckPerms, la référence de /aegis, les fichiers, le dépannage, puis la doc technique et le cahier des charges. Les bugs et les questions vont au suivi des tickets. Licence : LGPL-3.0-only.

Prérequis

Minecraft 26.3, 26.2 ou 26.1.2, un jar par version : prenez celui de votre jeu. Un serveur dédié : le mod est côté serveur seul, un client qui le trouve dans ses mods ne le charge pas, et les joueurs n'ont rien à installer. Fabric Loader 0.19.5 ou plus récent, Fabric Language Kotlin 1.14.1 ou plus récent, et la Fabric API de votre version : 0.163.0 ou plus récente pour 26.3, 0.161.0 pour 26.2, 0.155.3 pour 26.1.2. Java 25.