Wings Configuration

Comprehensive guide to Wings configuration options

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 [e-mail]

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:

1. Navigate to Admin Panel → Nodes
2. Click your node
3. Go to Configuration tab
4. Copy the auto-generated configuration

The Panel configuration ensures all URLs and tokens match correctly.

Updating Configuration

When updating configuration:

1. Edit config file

   nano /etc/pterodactyl/config.yml
   
2. Validate changes

   wings configure --check
   
3. Restart Wings

   systemctl restart wings
   
4. 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