Wings Configuration

Configuration File

Wings uses a YAML configuration file located at /etc/pterodactyl/config.yml. This file controls all aspects of Wings behavior.

Always restart Wings after making configuration changes: systemctl restart wings

Complete Configuration Example

/etc/pterodactyl/config.yml

debug: false
uuid: 12345678-1234-1234-1234-123456789012
token_id: your-token-id
token: your-token-secret

api:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert: /etc/letsencrypt/live/node.example.com/fullchain.pem
    key: /etc/letsencrypt/live/node.example.com/privkey.pem
  upload_limit: 100

system:
  root_directory: /var/lib/pterodactyl/volumes
  data: /var/lib/pterodactyl
  log_directory: /var/log/pterodactyl
  sftp:
    bind_port: 2022
    bind_address: 0.0.0.0
    read_only: false
  username: pterodactyl
  timezone: UTC
  user:
    rootless:
      enabled: false
      container_uid: 0
      container_gid: 0
  backup_concurrency: 2
  transfer_concurrency: 2

remote: https://panel.example.com

allowed_mounts: []
allowed_origins: []

throttles:
  enabled: true
  lines: 2000
  maximum_trigger_count: 10
  line_reset_interval: 10

Core Settings

Debug Mode

debug: false

Type: Boolean
Default: false
Description: Enables verbose logging for troubleshooting

Enable debug mode temporarily when troubleshooting issues. Disable it in production as it generates significant log output.

Node Authentication

uuid: 12345678-1234-1234-1234-123456789012
token_id: your-token-id
token: your-token-secret

uuid: Unique identifier for this node (from Panel)
token_id: Authentication token ID (from Panel)
token: Secret token for API authentication (from Panel)

These values are automatically generated by the Panel. Never share these credentials or commit them to version control.

API Configuration

Host and Port

api:
  host: 0.0.0.0
  port: 8080

host: IP address to bind Wings API (use 0.0.0.0 for all interfaces)
port: Port for Wings API (default: 8080)

If changing the port, update your Panel’s node configuration and firewall rules accordingly.

SSL/TLS

api:
  ssl:
    enabled: true
    cert: /etc/letsencrypt/live/node.example.com/fullchain.pem
    key: /etc/letsencrypt/live/node.example.com/privkey.pem

enabled: Enable HTTPS for Wings API
cert: Path to SSL certificate file
key: Path to SSL private key file

SSL is required for production environments. The Panel will not communicate with Wings over plain HTTP in production.

Upload Limit

api:
  upload_limit: 100

Type: Integer (MB)
Default: 100
Description: Maximum file upload size via Wings API in megabytes

Increase this if users need to upload larger files through the Panel’s file manager:

api:
  upload_limit: 500  # Allow 500MB uploads

System Configuration

Directories

system:
  root_directory: /var/lib/pterodactyl/volumes
  data: /var/lib/pterodactyl
  log_directory: /var/log/pterodactyl

root_directory: Where server files are stored
data: Wings internal data (configs, archives, etc.)
log_directory: Where Wings logs are written

Use a separate disk or partition for root_directory to prevent servers from filling up the system disk.

SFTP Configuration

system:
  sftp:
    bind_port: 2022
    bind_address: 0.0.0.0
    read_only: false

bind_port: Port for SFTP server (default: 2022)
bind_address: IP to bind SFTP server
read_only: Set to true to make all SFTP access read-only

Users connect via SFTP using the format:

sftp -P 2022 [email protected]

The SFTP authentication is handled by the Panel’s /api/remote/sftp/auth endpoint (app/Http/Controllers/Api/Remote/SftpAuthenticationController.php).

Timezone

system:
  timezone: UTC

Set the timezone for log timestamps and scheduled tasks. Use standard timezone identifiers:

system:
  timezone: America/New_York

System User

system:
  username: pterodactyl

Type: String
Default: pterodactyl
Description: System user Wings runs as (currently Wings runs as root)

Rootless Containers

system:
  user:
    rootless:
      enabled: false
      container_uid: 0
      container_gid: 0

enabled: Run containers as non-root user
container_uid: UID for container processes
container_gid: GID for container processes

Rootless mode is experimental. Most game servers expect to run as root and may fail with rootless containers.

Concurrency Settings

Backup Concurrency

system:
  backup_concurrency: 2

Type: Integer
Default: 2
Description: Number of backups that can run simultaneously

Increase on high-performance nodes:

system:
  backup_concurrency: 4  # Allow 4 simultaneous backups

Transfer Concurrency

system:
  transfer_concurrency: 2

Type: Integer
Default: 2
Description: Number of server transfers that can run simultaneously

Remote Panel URL

remote: https://panel.example.com

Type: String (URL)
Description: Full URL to your Pterodactyl Panel

This URL must exactly match your Panel’s configured URL. Include the protocol (https://) and exclude trailing slashes.

Allowed Mounts

allowed_mounts:
  - /mnt/shared-data
  - /opt/game-configs

Type: Array of paths
Default: Empty array
Description: Host directories that can be mounted into containers

Only add paths you trust. Mounted directories are accessible to game servers and could be modified or deleted.

Example for read-only shared configs:

allowed_mounts:
  - /opt/shared-configs

Then configure the mount in the Panel as:

Source: /opt/shared-configs
Target: /mnt/configs
Read Only: ✓

Allowed Origins

allowed_origins:
  - https://panel.example.com
  - https://admin.example.com

Type: Array of URLs
Default: Empty array (allows all origins)
Description: CORS allowed origins for Wings API

Restrict WebSocket console access:

allowed_origins:
  - https://panel.example.com

Console Throttles

Wings can throttle servers that spam the console to prevent resource exhaustion:

throttles:
  enabled: true
  lines: 2000
  maximum_trigger_count: 10
  line_reset_interval: 10

enabled: Enable console output throttling
lines: Lines per interval before throttling
maximum_trigger_count: How many times throttle can trigger before killing server
line_reset_interval: Seconds between throttle resets

Increase lines if legitimate servers are being throttled during startup:

throttles:
  lines: 5000  # Allow more output

Environment Variables

You can override certain config values with environment variables:

/etc/systemd/system/wings.service

[Service]
Environment="WINGS_DEBUG=true"
Environment="WINGS_UID=988"
Environment="WINGS_GID=988"

Common environment variables:

WINGS_DEBUG: Enable debug mode
WINGS_CONFIG_PATH: Custom config file path
WINGS_UID: User ID to run as
WINGS_GID: Group ID to run as

Configuration Validation

Validate your configuration before restarting Wings:

# Test configuration
wings configure --check

# Test Wings startup
wings --debug

Common Configurations

High-Performance Node

api:
  upload_limit: 500

system:
  backup_concurrency: 4
  transfer_concurrency: 3

throttles:
  enabled: true
  lines: 5000

Secure Production Node

debug: false

api:
  ssl:
    enabled: true
    cert: /etc/letsencrypt/live/node.example.com/fullchain.pem
    key: /etc/letsencrypt/live/node.example.com/privkey.pem

allowed_origins:
  - https://panel.example.com

throttles:
  enabled: true

Development Node

debug: true

api:
  ssl:
    enabled: false

throttles:
  enabled: false

Configuration from Panel

The Panel generates Wings configuration through the node management interface:

Navigate to Admin Panel → Nodes
Click your node
Go to Configuration tab
Copy the auto-generated configuration

The Panel configuration ensures all URLs and tokens match correctly.

Updating Configuration

When updating configuration:

Edit config file

nano /etc/pterodactyl/config.yml

Validate changes

wings configure --check

Restart Wings

systemctl restart wings

Verify status

systemctl status wings
journalctl -u wings -n 50

Next Steps

Docker Management

Learn how Wings manages containers

Networking

Configure networking and ports

Security

Secure your Wings installation

Monitoring

Monitor Wings performance

Getting Started

Operations

Configuration File

Complete Configuration Example

Core Settings

Debug Mode

Node Authentication

API Configuration

Host and Port

SSL/TLS

Upload Limit

System Configuration

Directories

SFTP Configuration

Timezone

System User

Rootless Containers

Concurrency Settings

Backup Concurrency

Transfer Concurrency

Remote Panel URL

Allowed Mounts

Allowed Origins

Console Throttles

Environment Variables

Configuration Validation

Common Configurations

High-Performance Node

Secure Production Node

Development Node

Configuration from Panel

Updating Configuration

Next Steps

Docker Management

Networking

Security

Monitoring

Build docs developers (and LLMs) love

Getting Started

Operations

​Configuration File

​Complete Configuration Example

​Core Settings

​Debug Mode

​Node Authentication

​API Configuration

​Host and Port

​SSL/TLS

​Upload Limit

​System Configuration

​Directories

​SFTP Configuration

​Timezone

​System User

​Rootless Containers

​Concurrency Settings

​Backup Concurrency

​Transfer Concurrency

​Remote Panel URL

​Allowed Mounts

​Allowed Origins

​Console Throttles

​Environment Variables

​Configuration Validation

​Common Configurations

​High-Performance Node

​Secure Production Node

​Development Node

​Configuration from Panel

​Updating Configuration

​Next Steps

Docker Management

Networking

Security

Monitoring

Build docs developers (and LLMs) love

Configuration File

Complete Configuration Example

Core Settings

Debug Mode

Node Authentication

API Configuration

Host and Port

SSL/TLS

Upload Limit

System Configuration

Directories

SFTP Configuration

Timezone

System User

Rootless Containers

Concurrency Settings

Backup Concurrency

Transfer Concurrency

Remote Panel URL

Allowed Mounts

Allowed Origins

Console Throttles

Environment Variables

Configuration Validation

Common Configurations

High-Performance Node

Secure Production Node

Development Node

Configuration from Panel

Updating Configuration

Next Steps