Configuration

Configure Wings with all available settings and options

Wings uses a YAML configuration file located at /etc/pterodactyl/config.yml by default. This guide covers all configuration options based on the actual source code.

Auto-Configuration (Recommended)

The easiest way to configure Wings is using the automatic configuration command:

sudo wings configure --panel-url https://panel.example.com --token YOUR_API_TOKEN --node 1

This command fetches the configuration from your Panel and automatically creates the config file (see cmd/configure.go:48).

Auto-Configure Options

Flag	Description
--panel-url	Panel URL (e.g., https://panel.example.com)
--token	Panel API token
--node	Node ID from the Panel
--config-path	Config file location (default: /etc/pterodactyl/config.yml)
--override	Override existing configuration
--allow-insecure	Skip SSL certificate verification

Use --allow-insecure only for testing with self-signed certificates.

Manual Configuration

For manual configuration or customization, create /etc/pterodactyl/config.yml.

Basic Configuration Structure

/etc/pterodactyl/config.yml

# Panel connection settings
remote: 'https://panel.example.com'
token_id: 'your-token-id'
token: 'your-token'

# Application settings
app_name: 'Pterodactyl'
debug: false

# API configuration
api:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: false
    cert: /etc/letsencrypt/live/example.com/fullchain.pem
    key: /etc/letsencrypt/live/example.com/privkey.pem
  upload_limit: 100

# System configuration
system:
  root_directory: /var/lib/pterodactyl
  log_directory: /var/log/pterodactyl
  data: /var/lib/pterodactyl/volumes
  archive_directory: /var/lib/pterodactyl/archives
  backup_directory: /var/lib/pterodactyl/backups
  tmp_directory: /tmp/pterodactyl
  username: pterodactyl
  timezone: UTC
  
  # SFTP configuration
  sftp:
    bind_address: 0.0.0.0
    bind_port: 2022
    read_only: false

# Docker configuration
docker:
  network:
    interface: 172.18.0.1
    name: pterodactyl_nw
    network_mode: pterodactyl_nw
    driver: bridge
  tmpfs_size: 100
  container_pid_limit: 512

Configuration Reference

Panel Connection

Settings for connecting Wings to your Panel.

remote · string · required

Panel URL (e.g., https://panel.example.com)

token_id · string · required

Token ID from Panel node configuration

token · string · required

Authentication token from Panel node configuration

remote_query.timeout · integer · default: "30"

API request timeout in seconds (see config/config.go:110)

remote_query.boot_servers_per_page · integer · default: "50"

Number of servers to load per API request (see config/config.go:121)

API Configuration

Configure the Wings API server.

api.host · string · default: "0.0.0.0"

Interface to bind the API server to

api.port · integer · default: "8080"

Port for the API server

api.ssl.enabled · boolean · default: "false"

Enable SSL/TLS for the API

api.ssl.cert · string

Path to SSL certificate file

api.ssl.key · string

Path to SSL private key file

api.upload_limit · integer · default: "100"

Maximum file upload size in MB (see config/config.go:96)

api.trusted_proxies · array

List of trusted proxy IPs for X-Forwarded-For headers

api:
  trusted_proxies:
    - 127.0.0.1
    - 172.18.0.0/16

System Configuration

Core system settings for Wings operation.

system.root_directory · string · default: "/var/lib/pterodactyl"

Root data directory for all Pterodactyl data

system.data · string · default: "/var/lib/pterodactyl/volumes"

Directory for server files

system.archive_directory · string · default: "/var/lib/pterodactyl/archives"

Directory for server transfer archives

system.backup_directory · string · default: "/var/lib/pterodactyl/backups"

Directory for local backups

system.log_directory · string · default: "/var/log/pterodactyl"

Directory for Wings logs

system.tmp_directory · string · default: "/tmp/pterodactyl"

Temporary directory for installations (see config/config.go:143)

system.username · string · default: "pterodactyl"

System user for server files (see config/config.go:146)

system.timezone · string · default: "auto-detected"

Timezone for containers (auto-detected or manually set)

system.disk_check_interval · integer · default: "150"

Seconds between disk usage checks. Set to 0 to disable (see config/config.go:223)

Setting this too low can cause performance issues

system.check_permissions_on_boot · boolean · default: "true"

Check file permissions when starting servers (see config/config.go:238)

system.enable_log_rotate · boolean · default: "true"

Enable automatic log rotation configuration (see config/config.go:242)

SFTP Configuration

Configure the built-in SFTP server.

system.sftp.bind_address · string · default: "0.0.0.0"

Interface to bind SFTP server to (see config/config.go:67)

system.sftp.bind_port · integer · default: "2022"

Port for SFTP server (see config/config.go:69)

system.sftp.read_only · boolean · default: "false"

Disable write operations on SFTP (see config/config.go:71)

Docker Configuration

Configure Docker integration.

Network Settings

docker:
  network:
    # Network interface IP
    interface: 172.18.0.1
    
    # Network name
    name: pterodactyl_nw
    
    # Docker network driver
    driver: bridge
    
    # Network mode for containers
    network_mode: pterodactyl_nw
    
    # Internal network (no internet access)
    is_internal: false
    
    # Enable inter-container communication
    enable_icc: true
    
    # Network MTU
    network_mtu: 1500
    
    # DNS servers for containers
    dns:
      - 1.1.1.1
      - 1.0.0.1
    
    # Network interfaces
    interfaces:
      v4:
        subnet: 172.18.0.0/16
        gateway: 172.18.0.1
      v6:
        subnet: fdba:17c8:6c94::/64
        gateway: fdba:17c8:6c94::1011

Network configuration is defined in config/config_docker.go:12-42.

Container Settings

docker.tmpfs_size · integer · default: "100"

Size of /tmp directory in containers (MB) (see config/config.go:60)

docker.container_pid_limit · integer · default: "512"

Maximum processes per container (see config/config.go:66)

docker.installer_limits.memory · integer · default: "1024"

Memory limit for installer containers (MB) (see config/config.go:73)

docker.installer_limits.cpu · integer · default: "100"

CPU limit for installer containers (%) (see config/config.go:74)

Memory Overhead

Configure memory overhead for containers to prevent OOM errors:

docker:
  overhead:
    # Override default multipliers
    override: false
    
    # Default multiplier (5%)
    default_multiplier: 1.05
    
    # Memory-based multipliers
    multipliers:
      2048: 1.15  # 15% for <= 2GB
      4096: 1.10  # 10% for <= 4GB

Default overhead (when override is false): 15% for ≤2GB, 10% for ≤4GB, 5% otherwise (see config/config_docker.go:154).

Docker Registry Authentication

Authenticate with private Docker registries:

docker:
  registries:
    ghcr.io:
      username: your-username
      password: your-token
    registry.example.com:
      username: user
      password: pass

Advanced System Settings

Rootless Mode

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

Rootless mode is experimental. Enable only if you understand the implications (see config/config.go:159).

Passwd File Generation

system:
  passwd:
    enabled: false
    directory: /run/wings/etc

Generates /etc/passwd and /etc/group files for containers (see config/config.go:177).

Machine ID

system:
  machine_id:
    enabled: true
    directory: /run/wings/machine-id

Mounts generated /etc/machine-id files (see config/config.go:196).

Crash Detection

system:
  crash_detection:
    enabled: true
    detect_clean_exit_as_crash: true
    timeout: 60

system.crash_detection.enabled · boolean · default: "true"

Enable crash detection globally (see config/config.go:260)

system.crash_detection.detect_clean_exit_as_crash · boolean · default: "true"

Detect clean exits as crashes if unexpected (see config/config.go:265)

system.crash_detection.timeout · integer · default: "60"

Seconds between crashes before auto-restart stops (see config/config.go:270)

Backup Configuration

system:
  backups:
    # Write speed limit in MiB/s (0 = unlimited)
    write_limit: 0
    
    # Compression level: none, best_speed, best_compression
    compression_level: best_speed

Backup settings are defined in config/config.go:273-292.

Transfer Configuration

system:
  transfers:
    # Download speed limit in MiB/s (0 = unlimited)
    download_limit: 0

Console Throttling

throttles:
  enabled: true
  lines: 2000
  line_reset_interval: 100

Prevents console spam (see config/config.go:304).

Environment Variables

Wings supports environment variable expansion in configuration:

Token from Environment

token_id: '${WINGS_TOKEN_ID}'
token: '${WINGS_TOKEN}'

Token from File

token_id: 'file:///etc/pterodactyl/token_id'
token: 'file:///etc/pterodactyl/token'

Systemd Credentials

token_id: 'file://${CREDENTIALS_DIRECTORY}/token_id'
token: 'file://${CREDENTIALS_DIRECTORY}/token'

Environment expansion is handled in config/config.go:844. The file:// prefix reads tokens from files.

Example Configurations

Basic

remote: 'https://panel.example.com'
token_id: 'your-token-id'
token: 'your-token'

api:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: false

system:
  root_directory: /var/lib/pterodactyl
  username: pterodactyl
  sftp:
    bind_address: 0.0.0.0
    bind_port: 2022

Production with SSL

remote: 'https://panel.example.com'
token_id: 'file://${CREDENTIALS_DIRECTORY}/token_id'
token: 'file://${CREDENTIALS_DIRECTORY}/token'

debug: false

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
  trusted_proxies:
    - 127.0.0.1

system:
  root_directory: /var/lib/pterodactyl
  username: pterodactyl
  disk_check_interval: 150
  check_permissions_on_boot: true
  sftp:
    bind_address: 0.0.0.0
    bind_port: 2022

docker:
  network:
    interface: 172.18.0.1
    name: pterodactyl_nw
  tmpfs_size: 100
  container_pid_limit: 512

High Performance

remote: 'https://panel.example.com'
token_id: 'your-token-id'
token: 'your-token'

api:
  host: 0.0.0.0
  port: 8080
  upload_limit: 500

system:
  root_directory: /var/lib/pterodactyl
  username: pterodactyl
  disk_check_interval: 300
  check_permissions_on_boot: false
  activity_send_interval: 30
  activity_send_count: 200
  sftp:
    bind_address: 0.0.0.0
    bind_port: 2022
  backups:
    write_limit: 0
    compression_level: best_speed
  transfers:
    download_limit: 0

docker:
  container_pid_limit: 1024
  use_performant_inspect: true

Validating Configuration

Test your configuration:

# Validate configuration file
sudo wings --config /etc/pterodactyl/config.yml --debug

# Check for errors in logs
sudo journalctl -u wings -n 50

Troubleshooting

Configuration Not Found

Ensure the config file exists:

ls -la /etc/pterodactyl/config.yml

Default location: /etc/pterodactyl/config.yml (see config/config.go:31)

Invalid YAML Syntax

Validate YAML syntax:

# Install yamllint
sudo apt install yamllint

# Check syntax
yamllint /etc/pterodactyl/config.yml

Permission Errors

Check file permissions:

# Config should be readable by root
sudo chmod 600 /etc/pterodactyl/config.yml
sudo chown root:root /etc/pterodactyl/config.yml

Next Steps

Panel Configuration

Configure the node in your Pterodactyl Panel