Skip to main content
Pumpkin’s permission system controls player access through operators (ops) and whitelists, matching vanilla Minecraft behavior.

​
Permission Levels

Pumpkin uses five permission levels (0-4) that determine what commands and actions a player can perform:
​
Zero
0
Normal Player - Can use basic commands only.
​
One
1
Moderator - Can bypass spawn protection.
​
Two
2
Gamemaster - Can use additional commands and command blocks.
​
Three
3
Admin - Can manage multiplayer commands and moderate players.
​
Four
4
Owner - Full access to all commands and server management.

​
Operators (Ops)

Operators have elevated permissions on the server. The ops list is stored in ops.json in the config directory.

​
Op Structure

Each operator entry contains:
​
uuid
Uuid
required
The UUID of the operator.
​
name
string
required
The username of the operator.
​
level
PermissionLvl
required
The permission level assigned to this operator (Zero through Four).
​
bypasses_player_limit
boolean
required
Whether this operator can join even when the server is full.

​
Example ops.json

ops.json
[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch",
    "level": 4,
    "bypasses_player_limit": true
  },
  {
    "uuid": "61699b2e-1234-5678-9abc-def012345678",
    "name": "Moderator",
    "level": 1,
    "bypasses_player_limit": false
  }
]

​
Adding Operators

Use the /op command in-game or via console: 
op <player>
The permission level assigned is controlled by the op_permission_level setting in configuration.toml:
configuration.toml
op_permission_level = "Four"  # Default level for /op command

​
Default Permission Level

Players not in the ops file receive the default permission level, configured in features.toml:
features.toml
[commands]
default_op_level = "Zero"  # Non-op players get level 0

​
Whitelist

The whitelist restricts server access to approved players. The whitelist is stored in whitelist.json in the config directory.

​
Enabling the Whitelist

Configure whitelist behavior in configuration.toml:
​
white_list
boolean
default:"false"
Whether the whitelist is enabled. When true, only whitelisted players can join.
​
enforce_whitelist
boolean
default:"false"
Whether to immediately kick non-whitelisted players when the whitelist is enabled.
  • true - Non-whitelisted players are kicked immediately when whitelist is activated
  • false - Non-whitelisted players currently online can stay until they disconnect
configuration.toml
white_list = true
enforce_whitelist = true

​
Whitelist Entry Structure

Each whitelist entry contains:
​
uuid
Uuid
required
The UUID of the whitelisted player.
​
name
string
required
The username of the whitelisted player.

​
Example whitelist.json

whitelist.json
[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  },
  {
    "uuid": "61699b2e-1234-5678-9abc-def012345678",
    "name": "TrustedPlayer"
  }
]

​
Managing the Whitelist

Use these commands to manage the whitelist: 
# Add a player to the whitelist
whitelist add <player>

# Remove a player from the whitelist
whitelist remove <player>

# Enable the whitelist
whitelist on

# Disable the whitelist
whitelist off

# Reload the whitelist from disk
whitelist reload

# List all whitelisted players
whitelist list

​
Permission Best Practices

Use Minimal Permissions

Grant the lowest permission level needed for each role. Not everyone needs level 4 access.

Enable Whitelist for Private Servers

Use the whitelist for private or semi-private servers to control who can join.

Ops Bypass Player Limit

Use bypasses_player_limit for trusted admins so they can always join.

Regularly Review Access

Periodically review ops.json and whitelist.json to remove inactive players.

​
Validation Rules

Pumpkin validates permission configuration on startup:
  • Permission levels must be Zero, One, Two, Three, or Four
  • UUIDs must be valid UUID format
  • When white_list = true, only whitelisted players can connect
  • When enforce_whitelist = true, non-whitelisted players are kicked immediately

​
Manual File Editing

You can manually edit ops.json and whitelist.json while the server is running, then reload: 
# Reload whitelist
whitelist reload

# For ops, restart the server or use /op and /deop commands
JSON Syntax: Ensure valid JSON syntax when manually editing these files. Invalid JSON will cause the server to fail loading the file.

​
Permission Level Reference

LevelNameAbilities
0NormalBasic commands only
1ModeratorBypass spawn protection
2GamemasterUse command blocks, more commands
3AdminMultiplayer management commands
4OwnerAll commands, server management

Build docs developers (and LLMs) love

Get started for freeTalk to us