Node Management

Nodes are the physical or virtual servers that host game server containers. Each node runs the Pterodactyl Wings daemon, which manages Docker containers and communicates with the Panel.

Node Overview

A node represents a server in your infrastructure that will host game servers. From app/Models/Node.php:88-95:

protected $fillable = [
    'public', 'name', 'location_id',
    'description', 'fqdn', 'scheme', 'behind_proxy',
    'memory', 'memory_overallocate', 'disk',
    'disk_overallocate', 'upload_size', 'daemonBase',
    'daemonSFTP', 'daemonListen',
    'description', 'maintenance_mode',
];

Creating a Node

Navigate to Nodes

Go to Admin Panel → Nodes → Create New

Basic Configuration

Node Identity

Name: Descriptive name (1-100 characters, letters, numbers, spaces, dots, hyphens)
Description: Optional description of the node
Location: Select a location to organize this node
Public: Whether this node is visible for auto-deployment

Connection Settings

Network Configuration

FQDN: Fully qualified domain name or IP address
Scheme: http or https (use HTTPS in production)
Behind Proxy: Enable if using a reverse proxy (Cloudflare, nginx, etc.)
Daemon Port: Port Wings listens on (default: 8080)
SFTP Port: Port for SFTP file access (default: 2022)

Resource Limits

Available Resources

Total Memory: RAM in MB available for servers
Memory Over-allocation: Percentage to allow over memory limit (default: 0)
Total Disk: Disk space in MB available for servers
Disk Over-allocation: Percentage to allow over disk limit (default: 0)

Advanced Settings

Additional Configuration

Upload Limit: Max upload size in MB (default: 100)
Daemon Server File Directory: Base path for server files (default: /var/lib/pterodactyl/volumes)
Maintenance Mode: Prevent new servers from starting

Create Node

Click Create NodeA configuration file will be generated for Wings.

Node Validation Rules

From app/Models/Node.php:98-115:

public static array $validationRules = [
    'name' => 'required|regex:/^([\w .-]{1,100})$/',
    'description' => 'string|nullable',
    'location_id' => 'required|exists:locations,id',
    'public' => 'boolean',
    'fqdn' => 'required|string',
    'scheme' => 'required',
    'behind_proxy' => 'boolean',
    'memory' => 'required|numeric|min:1',
    'memory_overallocate' => 'required|numeric|min:-1',
    'disk' => 'required|numeric|min:1',
    'disk_overallocate' => 'required|numeric|min:-1',
    'daemonBase' => 'sometimes|required|regex:/^([\/ ][\d\w.\-\/]+)$/',
    'daemonSFTP' => 'required|numeric|between:1,65535',
    'daemonListen' => 'required|numeric|between:1,65535',
    'maintenance_mode' => 'boolean',
    'upload_size' => 'int|min:1',
];

Configuring Wings

After creating a node, you need to install and configure Wings:

View Configuration

Click on the node you just created to view its details

Copy Configuration

The Panel generates a configuration file automatically. You can view it in:

YAML format (for manual setup)
JSON format (for programmatic setup)

Install Wings

On your node server, install Wings:

curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings

Create Configuration Directory

mkdir -p /etc/pterodactyl

Save Configuration

Save the generated configuration to /etc/pterodactyl/config.yml

Start Wings

wings --debug

Or use systemd for production:

systemctl enable --now wings

Auto-Configuration

You can also use the auto-deploy feature:

Run this command on your node server:

cd /etc/pterodactyl
wings configure --panel-url https://panel.example.com --token YOUR_TOKEN

The configuration will be automatically downloaded and saved

Connection Address

Wings is accessed via a connection string (from app/Models/Node.php:134-137):

public function getConnectionAddress(): string
{
    return sprintf('%s://%s:%s', $this->scheme, $this->fqdn, $this->daemonListen);
}

Example: https://node1.example.com:8080

Resource Over-allocation

Over-allocation allows you to allocate more resources than physically available:

Memory Over-allocation

0%: Can allocate up to total memory (recommended)
50%: Can allocate 150% of total memory
-1: Unlimited over-allocation

Example:

Node has 16GB (16384MB) RAM
Over-allocation: 50%
Can allocate: 24576MB to servers

Disk Over-allocation

0%: Can allocate up to total disk (recommended)
20%: Can allocate 120% of total disk
-1: Unlimited over-allocation

Over-allocation can lead to resource contention and poor performance. Use cautiously and monitor resource usage.

Node Viability Check

The Panel checks if a node can host a new server (from app/Models/Node.php:242-249):

public function isViable(int $memory, int $disk): bool
{
    $memoryLimit = $this->memory * (1 + ($this->memory_overallocate / 100));
    $diskLimit = $this->disk * (1 + ($this->disk_overallocate / 100));

    return ($this->sum_memory + $memory) <= $memoryLimit 
        && ($this->sum_disk + $disk) <= $diskLimit;
}

This ensures the node has sufficient resources before deployment.

Maintenance Mode

When maintenance mode is enabled:

Existing servers can continue running
Users cannot start stopped servers
No new servers can be deployed
Useful for updates or troubleshooting

Check maintenance status (from app/Models/Node.php:196-199):

public function isUnderMaintenance(): bool
{
    return $this->maintenance_mode;
}

Allocations

After creating a node, you must add IP allocations:

Navigate to Node Allocations

Click on the node, then go to the Allocation tab

Add IP Address

Enter the IP address to allocate (usually the node’s public IP)

Specify Port Range

Enter port range:

Single port: 25565
Range: 25565-25575
Multiple: 25565,25566,25567

Set Alias (Optional)

Add a friendly name for the allocation

Create Allocations

Click Submit to create the allocations

Allocations are required before creating servers. Each server needs at least one allocation for its primary port.

SSL/TLS Configuration

Using HTTPS (Recommended)

For production deployments:

Set Scheme to https
Ensure SSL certificates are installed on the node at:
- /etc/letsencrypt/live/YOUR_FQDN/fullchain.pem
- /etc/letsencrypt/live/YOUR_FQDN/privkey.pem
Wings will automatically use these certificates

The SSL paths are defined in config (from app/Models/Node.php:153-155):

'ssl' => [
    'cert' => '/etc/letsencrypt/live/' . Str::lower($this->fqdn) . '/fullchain.pem',
    'key' => '/etc/letsencrypt/live/' . Str::lower($this->fqdn) . '/privkey.pem',
],

Behind Proxy

If using a reverse proxy (nginx, Cloudflare):

Enable Behind Proxy
Set Scheme to https
Wings will disable SSL and listen on HTTP
Proxy handles SSL termination

Default Settings

Nodes are created with these defaults (from app/Models/Node.php:120-129):

protected $attributes = [
    'public' => true,
    'behind_proxy' => false,
    'memory_overallocate' => 0,
    'disk_overallocate' => 0,
    'daemonBase' => '/var/lib/pterodactyl/volumes',
    'daemonSFTP' => 2022,
    'daemonListen' => 8080,
    'maintenance_mode' => false,
];

System Information

The node detail page shows real-time information:

Wings Version: Currently running Wings version
System Load: CPU load average
Memory Usage: Used vs. total RAM
Disk Usage: Used vs. total disk space
Container Information: Running containers

This information is fetched from Wings in real-time. If Wings is offline, this data won’t be available.

Node Security

Each node has authentication tokens:

daemon_token_id: 16-character token ID
daemon_token: 64-character encrypted token

These are automatically generated and used for Panel-Wings communication. From app/Models/Node.php:59-60:

public const DAEMON_TOKEN_ID_LENGTH = 16;
public const DAEMON_TOKEN_LENGTH = 64;

Mounts

Nodes can have mounts attached:

Shared directories
Read-only or read-write
Available to specific eggs
Configured in the Mounts section

Troubleshooting

Connection Failed

If the Panel can’t connect to Wings:

Verify Wings is running: systemctl status wings
Check firewall allows connections on daemon port
Verify FQDN resolves to correct IP
Check SSL certificates if using HTTPS
Review Wings logs: journalctl -u wings

Resource Over-allocation

If servers are slow:

Check actual resource usage on node
Reduce over-allocation percentages
Migrate servers to other nodes
Add more physical resources

Port Conflicts

If allocations aren’t working:

Ensure ports aren’t used by other services
Check firewall rules allow the ports
Verify Wings is binding to correct IP

Best Practices

Use HTTPS: Always use SSL/TLS in production
Limit Over-allocation: Keep at 0% or low percentages
Regular Updates: Keep Wings updated
Monitor Resources: Watch CPU, RAM, and disk usage
Separate Locations: Use locations to organize nodes geographically
Firewall Rules: Only expose necessary ports
Backup Configuration: Save Wings config files

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

Node Overview

Creating a Node

Node Validation Rules

Configuring Wings

Auto-Configuration

Connection Address

Resource Over-allocation

Memory Over-allocation

Disk Over-allocation

Node Viability Check

Maintenance Mode

Allocations

SSL/TLS Configuration

Using HTTPS (Recommended)

Behind Proxy

Default Settings

System Information

Node Security

Mounts

Troubleshooting

Connection Failed

Resource Over-allocation

Port Conflicts

Best Practices

Next Steps

Locations

Server Creation

Build docs developers (and LLMs) love

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Node Overview

​Creating a Node

​Node Validation Rules

​Configuring Wings

​Auto-Configuration

​Connection Address

​Resource Over-allocation

​Memory Over-allocation

​Disk Over-allocation

​Node Viability Check

​Maintenance Mode

​Allocations

​SSL/TLS Configuration

​Using HTTPS (Recommended)

​Behind Proxy

​Default Settings

​System Information

​Node Security

​Mounts

​Troubleshooting

​Connection Failed

​Resource Over-allocation

​Port Conflicts

​Best Practices

​Next Steps

Locations

Server Creation

Build docs developers (and LLMs) love

Node Overview

Creating a Node

Node Validation Rules

Configuring Wings

Auto-Configuration

Connection Address

Resource Over-allocation

Memory Over-allocation

Disk Over-allocation

Node Viability Check

Maintenance Mode

Allocations

SSL/TLS Configuration

Using HTTPS (Recommended)

Behind Proxy

Default Settings

System Information

Node Security

Mounts

Troubleshooting

Connection Failed

Resource Over-allocation

Port Conflicts

Best Practices

Next Steps