Permission System

Nimbus includes a full-featured permission system with group management, inheritance, tracks, meta-data, and an audit log. All permission data is stored centrally on the Nimbus controller and synced to all servers in real-time — no extra database setup needed on individual servers.

Overview

• Permission groups with inheritance, wildcards, and negation
• Tracks for promotion/demotion paths (e.g., Member → VIP → MVP → Admin)
• Meta-data on groups and players (arbitrary key-value pairs)
• Weight for conflict resolution between groups
• Audit log tracking all permission changes
• Permission debug explaining exactly why a permission is granted or denied
• LuckPerms integration as an alternative provider
• Real-time sync via WebSocket to all backend servers and the Velocity proxy

Providers

Nimbus supports two permission providers, configured per-server in the NimbusPerms plugin:

Built-in (default)

The built-in system stores everything on the Nimbus controller's database. Backend servers fetch permissions via the Nimbus API — no additional setup needed on individual servers.

# nimbus-perms config.yml
provider: builtin

Advantages:

• Zero configuration on backend servers
• Single source of truth (controller database)
• Works with SQLite, MySQL, or PostgreSQL
• Full integration with console commands, REST API, and WebSocket events

LuckPerms

Use LuckPerms as the permission engine. Nimbus reads display data (prefix, suffix) from LuckPerms and syncs it to the controller for proxy features (tab list, chat formatting, nametags).

# nimbus-perms config.yml
provider: luckperms

What Nimbus handles for you:

• Proxy display sync (tab prefixes, chat formatting, MOTD) — no extra Vault/TAB plugin needed on Velocity
• REST API exposes permission data from LuckPerms
• Console shows player display info from LuckPerms

What LuckPerms still handles:

• Permission storage and resolution on backend servers
• LuckPerms still needs its own shared database (MySQL/PostgreSQL) for multi-server permission sync — Nimbus syncs display data only, not permission nodes

Setup Wizard

During the initial setup, Nimbus asks which modules to install. If the Permissions module is selected (default), the NimbusPerms plugin is automatically deployed to all backend servers.

• Selected (default): NimbusPerms module is installed and its plugin deployed to backends
• Not selected: You can install LuckPerms or add the module later with modules install perms

Database Storage

Permissions are stored in the controller database, configurable via the [database] section in config/nimbus.toml:

[database]
type = "sqlite"  # or mysql, postgresql

By default, Nimbus uses SQLite with a database file at data/nimbus.db. For larger networks, switch to MySQL/MariaDB or PostgreSQL.

Database Schema

Group Properties

Permission Resolution

When checking a player's permissions:

1. Default group permissions (applies to everyone)
2. Parent groups resolved recursively (depth-first, parent before child)
3. Player's assigned groups layered on top
4. Negated permissions (prefixed with -) removed from the final set

Wildcard Matching

Negation

Prefix a permission with - to deny it:

perms group addperm Moderator nimbus.*
perms group addperm Moderator -nimbus.cloud.shutdown

Tracks

Tracks define ordered promotion/demotion paths through groups.

perms track create staff Member,Moderator,Admin
perms user promote Steve staff     # Member → Moderator
perms user promote Steve staff     # Moderator → Admin
perms user demote Steve staff      # Admin → Moderator

A player can only be on one group per track at a time. Promoting removes the current track group and assigns the next one.

Meta-Data

Arbitrary key-value pairs on groups and players. Useful for custom data that plugins can read via the API.

perms group meta set VIP color gold
perms group meta set VIP icon star
perms user meta set Steve coins 500
perms group meta list VIP
perms user meta list Steve

Permission Debug

The check command explains why a permission is granted or denied:

perms user check Steve nimbus.cloud.list

Output shows the resolution chain — which group granted it, via exact match or wildcard, and whether any negation was applied.

Audit Log

All permission changes are logged with timestamp, actor, action, and details:

perms audit          # last 20 entries
perms audit 50       # last 50 entries

Console Commands

Group Commands

User Commands

Track Commands

Other

API Endpoints

All endpoints require bearer token authentication.

Groups

Players

Tracks

Debug & Audit

Architecture

                    Nimbus Controller
                 ┌─────────────────────┐
                 │  PermissionManager   │
                 │  (DB: SQLite/MySQL)  │
                 │  REST API + Events   │
                 └────────┬────────────┘
                          │ WebSocket
            ┌─────────────┼─────────────┐
            ▼             ▼             ▼
     ┌──────────┐  ┌──────────┐  ┌──────────────┐
     │ Lobby-1  │  │ BedWars-1│  │ Velocity     │
     │ NimbusSDK│  │ NimbusSDK│  │ NimbusBridge │
     │ NimbusPerms│ │ NimbusPerms│ │ PermProvider │
     └──────────┘  └──────────┘  └──────────────┘

• Backend servers: NimbusPerms fetches permissions from the controller API on player join, applies via Bukkit PermissionAttachment, and listens for real-time changes
• Velocity proxy: NimbusBridge loads permissions from the controller API and provides them to Velocity's permission system
• All changes (console, API, LuckPerms sync) emit events that propagate to all connected servers instantly

Example Setup

Quick Start

perms group create VIP
perms group addperm VIP essentials.fly
perms group addperm VIP essentials.hat
perms group setprefix VIP "&6[VIP] "
perms group setpriority VIP 50
perms group setweight VIP 50

perms group setprefix Default "&7"
perms group setprefix Admin "&c[Admin] "

perms track create ranks Default,VIP,Admin
perms user promote Steve ranks    # Default → VIP
perms user addgroup Alex Admin

Result

• Steve: VIP permissions, prefix &6[VIP]
• Alex: Admin with *, prefix &c[Admin]
• New players: Default group automatically, prefix &7