Server Settings - Pterodactyl Panel

Server settings allow you to customize your server’s identity and perform maintenance operations like renaming, changing descriptions, updating Docker images, and reinstalling the server.

Server Information

View basic server information:

Get Server Details

GET /api/client/servers/{server}

Response

{
  "object": "server",
  "attributes": {
    "uuid": "7e8e8f18-25fa-4f9e-a13d-4d1c8e8b8f9e",
    "name": "My Minecraft Server",
    "description": "A survival server for friends and family",
    "status": null,
    "node": "Node 01",
    "sftp_details": {
      "ip": "node01.example.com",
      "port": 2022
    },
    "limits": {
      "memory": 4096,
      "swap": 512,
      "disk": 10240,
      "io": 500,
      "cpu": 200,
      "threads": null
    }
  }
}

Renaming Server

Change your server’s name and description:

Rename Server

POST /api/client/servers/{server}/settings/rename
Content-Type: application/json

{
  "name": "Minecraft Survival World",
  "description": "Updated survival server with new plugins"
}

Success

HTTP/1.1 204 No Content

Navigate to Settings

Go to the Settings tab in your server panel.

Edit Name

Enter a new server name (1-191 characters).

Update Description

Optionally update the description to reflect server purpose or changes.

Save Changes

Click Save. Changes are immediate and don’t require a restart.

Validation Rules

Name Validation

{
  "name": "required|string|min:1|max:191",
  "description": "string"
}

Name: Required, 1-191 characters
Description: Optional, any length

Renaming doesn’t affect server files or functionality - it only changes how the server appears in the panel.

Docker Image Management

Docker images define the runtime environment for your server.

Available Images

Check which Docker images are available:

GET /api/client/servers/{server}/startup

Response

{
  "meta": {
    "docker_images": {
      "Java 17": "ghcr.io/pterodactyl/yolks:java_17",
      "Java 11": "ghcr.io/pterodactyl/yolks:java_11",
      "Java 8": "ghcr.io/pterodactyl/yolks:java_8"
    }
  }
}

Changing Docker Image

Update to a different Docker image:

Update Docker Image

POST /api/client/servers/{server}/settings/docker-image
Content-Type: application/json

{
  "docker_image": "ghcr.io/pterodactyl/yolks:java_17"
}

Success

HTTP/1.1 204 No Content

Changing Docker images requires restarting your server. Ensure the new image is compatible with your server software and plugins.

When to Change Images

Java Version Requirements

Different Minecraft versions require different Java versions:

Minecraft 1.17+: Requires Java 17
Minecraft 1.16.5: Works with Java 11 or 8
Minecraft 1.12.2 and older: Requires Java 8

Switch images when updating server versions.

Performance Optimization

Newer Java versions often have better performance:

Java 17 has improved garbage collection
Better memory management
Faster startup times

Plugin Compatibility

Some plugins require specific Java versions. Check plugin documentation before changing.

Restrictions

You can only change to images defined in the egg configuration:

Error: Custom Image Not Allowed

HTTP/1.1 400 Bad Request

{
  "errors": [
    {
      "code": "BadRequestHttpException",
      "detail": "This server's Docker image has been manually set by an administrator and cannot be updated."
    }
  ]
}

If the image was manually set by an admin, users cannot change it.

Server Reinstallation

Reinstall your server to start fresh:

Reinstall Server

POST /api/client/servers/{server}/settings/reinstall

Success

HTTP/1.1 202 Accepted

Reinstalling deletes ALL server files. This action is permanent and cannot be undone. Create a backup before reinstalling.

Reinstallation Process

Backup Your Server

Create a backup of all important files:

POST /api/client/servers/{server}/backups

Initiate Reinstall

Click Reinstall Server in the settings or use the API.

Server Goes Offline

Server status changes to installing. All actions are disabled.

Installation Runs

The egg’s installation script executes:

Deletes existing files
Downloads fresh server files
Runs initial setup commands

Restore from Backup

After installation completes, restore your backup if needed:

POST /api/client/servers/{server}/backups/{backup}/restore

When to Reinstall

Corrupted Server Files

If core server files are corrupted and causing crashes:

Reinstall provides clean server files
Restore your worlds/configs from backup after

Switching Server Types

When changing between server types:

Vanilla to Spigot
Spigot to Paper
Paper to Forge

Note: May require admin to change egg first.

Starting Fresh

Remove all customizations and start over:

Clean slate for testing
Remove all plugins/mods
Reset to default configuration

Failed Installation

If initial server installation failed:

Status shows install_failed
Reinstall runs installation script again

What Gets Deleted

Reinstallation removes:

All server files
Game worlds
Configuration files
Plugins/mods
Logs and cache

Reinstallation preserves:

Server settings (name, limits)
Database connections
Network allocations
Schedules and backups (the backup files themselves)
Startup variables

SFTP Access

SFTP (SSH File Transfer Protocol) provides direct file access:

SFTP Details

{
  "sftp_details": {
    "ip": "node01.example.com",
    "port": 2022
  }
}

Connecting via SFTP

Host: sftp://node01.example.com
Port: 2022
Username: {your_panel_username}.{server_id}
Password: {your_panel_password}

SFTP Username Format

{panel_username}.{server_id}

Example:

Panel username: admin
Server UUID: 7e8e8f18-25fa-4f9e-a13d-4d1c8e8b8f9e
SFTP username: admin.7e8e8f18

The server ID is the first 8 characters of the UUID. You must use your panel password (not a separate SFTP password).

Server Debug Information

Useful information for troubleshooting:

Debug Info

{
  "uuid": "7e8e8f18-25fa-4f9e-a13d-4d1c8e8b8f9e",
  "identifier": "7e8e8f18",
  "node": "Node 01",
  "egg": "Minecraft Java Edition",
  "docker_image": "ghcr.io/pterodactyl/yolks:java_17",
  "created_at": "2025-01-10T08:00:00+00:00",
  "installed_at": "2025-01-10T08:05:32+00:00"
}

Include this information when requesting support.

Activity Logging

Settings changes are logged:

Example Logs

{
  "event": "server:settings.rename",
  "properties": {
    "old": "My Minecraft Server",
    "new": "Minecraft Survival World"
  }
}

{
  "event": "server:settings.description",
  "properties": {
    "old": "A survival server",
    "new": "Updated survival server with new plugins"
  }
}

{
  "event": "server:startup.image",
  "properties": {
    "old": "ghcr.io/pterodactyl/yolks:java_11",
    "new": "ghcr.io/pterodactyl/yolks:java_17"
  }
}

{
  "event": "server:reinstall"
}

Permissions Required

Settings operations require specific permissions:

Operation	Permission
Rename server	`settings.rename`
Change Docker image	`settings.docker-image`
Reinstall server	`settings.reinstall`
View SFTP details	`file.sftp`

Server owners always have all permissions. Subusers must be granted these permissions explicitly.

Best Practices

Descriptive Server Names

Use clear, descriptive names:

Good: “Minecraft 1.20 Survival”, “CS:GO Competitive”
Bad: “Server 1”, “Test”, “asdf”

Makes managing multiple servers easier.

Update Descriptions

Keep descriptions current:

Server type and version
Active plugins/mods
Special rules or features
Last major update date

Always Backup Before Reinstall

Create a backup before reinstalling:

# Create backup
POST /api/client/servers/{server}/backups

# Wait for completion, then reinstall
POST /api/client/servers/{server}/settings/reinstall

Test Docker Image Changes

Before changing Docker images on production servers:

Test on a development/staging server
Verify all plugins work
Check for errors in logs
Apply to production during off-peak hours

Troubleshooting

Cannot Rename Server

Verify you have settings.rename permission
Check name length (max 191 characters)
Ensure name isn’t empty
Try different characters if special chars fail

Docker Image Change Fails

Ensure image is in allowed list
Check if admin manually set image
Verify you have permission
Restart server after change

Reinstall Stuck

If reinstall doesn’t complete:

Check Wings daemon is running
Review Wings logs for errors
Verify node has internet access (to download files)
Contact administrator if stuck >30 minutes

SFTP Connection Failed

Verify SFTP port is correct
Check username format: username.serverid
Use panel password (not separate SFTP password)
Ensure Wings SFTP server is running
Check firewall allows SFTP port (usually 2022)

Documentation Index

​Server Information

​Renaming Server

​Validation Rules

​Docker Image Management

​Available Images

​Changing Docker Image

​When to Change Images

​Restrictions

​Server Reinstallation

​Reinstallation Process

​When to Reinstall

​What Gets Deleted

​SFTP Access

​Connecting via SFTP

​SFTP Username Format

​Server Debug Information

​Activity Logging

​Permissions Required

​Best Practices

​Troubleshooting

Server Information

Renaming Server

Validation Rules

Docker Image Management

Available Images

Changing Docker Image

When to Change Images

Restrictions

Server Reinstallation

Reinstallation Process

When to Reinstall

What Gets Deleted

SFTP Access

Connecting via SFTP

SFTP Username Format

Server Debug Information

Activity Logging

Permissions Required

Best Practices

Troubleshooting