Gradeway

A modern permission plugin for Paper, Bukkit, Velocity, and BungeeCord – one shared database, every server in sync.

Manage ranks, permissions, and temporary roles across your entire network from a single place.
Coming from LuckPerms? Import your existing data with one command.

Changelog · Documentation · Discord · API Reference

Note

Gradeway is in active development (0.x). It's ready to try, but expect changes between releases – back up your data before upgrading.

---

Why Gradeway?

• Your whole network, always in sync – change a rank on one server and every connected server picks it up instantly, no restarts or manual reloads.
• Temporary and pausable ranks – give someone vip for 30 days, or pause a staff role while they're on break without losing it.
• Know exactly why someone has a permission – /gradeway why shows the full chain (player → role → group → template), and /gradeway whocan lists everyone who has it.
• Promotion tracks – define a ladder like trial → mod → admin and promote or demote players along it.
• Permission templates – build a reusable set of permissions once and apply it to any role or player.
• Safe by default – destructive commands ask for confirmation, and full backups export and import with one command.
• Works with what you already have – plug in the database you already run, from SQLite on a single server to MySQL or Postgres for a whole network.

How it works

Gradeway is built around a few simple ideas:

1. Players get roles. A role like vip or mod is a bundle of permissions. Give a player a role – forever or for a limited time – and they get everything in it.
2. Roles can build on each other. Let admin inherit everything from mod, put related roles into a group so they share permissions, or reuse a template wherever you need the same set again.
3. Every server shares one database. Change something on one server and Gradeway tells all the others, so the whole network updates right away.

Steve ──► vip (30 days) ──► essentials.fly
      │                 └─► essentials.home
      └─► default ────────► essentials.spawn

When Steve runs a command, Gradeway looks at all his roles and answers one question: is he allowed? If you ever wonder why the answer is yes or no, /gradeway why shows you the path it took.

See it in action

/gradeway role create vip
/gradeway role modify vip permissions set essentials.fly
/gradeway player modify Steve roles add vip 30D
/gradeway why Steve essentials.fly

Coming from LuckPerms?

Run /lp export in LuckPerms, then import the file into Gradeway:

/gradeway migrate luckperms <file>

One thing to know: what LuckPerms calls a "group" is a role in Gradeway.

LuckPerms	Gradeway
Group (admin, default, …)	Role
Parent groups	Role parents
Primary group	Primary role
Track	Track
no equivalent	Group – a container that lets several roles share permissions and a default weight

The architecture guide explains the model in detail.

Getting started

1. Download Gradeway for your platform from Modrinth or Hangar.
2. Download the driver for your database and place it in the drivers/ folder.
3. Start your server and fill in your database credentials in the generated config.

The full installation guide covers every platform and option.

Which setup do I need?

Your setup	Database	Messaging
One server	SQLite or H2 – no database server needed	Not needed, you can turn it off
Proxy + a few servers	MySQL, MariaDB, or Postgres	Plugin Messaging (built in) or Redis
Large network	MySQL, MariaDB, or Postgres	Redis

Plugin Messaging works without any extra software, but it can only reach a server while a player is online there. Redis keeps every server in sync at all times, so it's the better choice once your network grows.

Compatibility

	Supported
Servers	Paper, Bukkit (26.1+)
Proxies	Velocity, BungeeCord
Databases	Postgres, MySQL, MariaDB, SQLite, SQL Server, Oracle, H2
Messaging	Redis, Plugin Messaging

See the compatibility documentation for the full overview.

For developers

Gradeway has a public API with events, actor tracking, and custom attribute types. See the developer guide and the API reference.

Building from source

Requires JDK 17+ to run Gradle; the JDK 21/25 toolchains are provisioned automatically on first build.

git clone https://github.com/GradientTim/gradeway.git
cd gradeway
./gradlew build

The database schema is documented as an interactive diagram.

Contributing

See CONTRIBUTING.md for the development setup and PR expectations. The Discord server is the fastest way to discuss a change before you start. Please also read the Code of Conduct and Security Policy.

License

Gradeway is licensed under the MIT License.