Quick Start Guide

Get Wings up and running in minutes with this step-by-step guide

Prerequisites

Before installing Wings, ensure your system meets the following requirements:

Operating System

Wings runs on Linux-based operating systems. Supported distributions include:

• Ubuntu 20.04+ (recommended)
• Debian 11+
• CentOS 8+ / Rocky Linux / AlmaLinux
• Fedora 35+

Docker Installation

Wings requires Docker to be installed and running:

• Docker Engine 20.10 or newer
• Docker must be running and accessible by the Wings process
• The user running Wings needs permission to interact with Docker

Panel Setup

You need a running Pterodactyl Panel instance:

• Panel version compatible with Wings
• A node created in the Panel admin area
• API credentials from the Panel for this node

Wings should be installed on a separate server from your Pterodactyl Panel for security and performance reasons. Installing both on the same server is not recommended for production use.

Installation Steps

1. Install Docker

   If Docker is not already installed, install it using the official Docker installation script:

   Ubuntu/Debian

   curl -fsSL https://get.docker.com | sh
   systemctl enable --now docker
   

   curl -fsSL https://get.docker.com | sh
   systemctl enable --now docker
   

   Verify Docker is running:

   docker --version
   docker ps
   

   The Docker installation script automatically handles repository setup and package installation for most distributions.

2. Create Required Directories

   Wings uses specific directories for configuration and data storage. Create them with appropriate permissions:

   # Create configuration directory
   mkdir -p /etc/pterodactyl
   
   # Create data directories
   mkdir -p /var/lib/pterodactyl/volumes
   mkdir -p /var/lib/pterodactyl/backups
   mkdir -p /var/lib/pterodactyl/archives
   
   # Create log directory
   mkdir -p /var/log/pterodactyl
   

   These are the default directories. You can customize them in the Wings configuration file if needed.

3. Download Wings Binary

   Download the latest Wings binary from the official GitHub releases:

   # Download the latest release
   curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64"
   
   # Make it executable
   chmod +x /usr/local/bin/wings
   

   For ARM64 systems, use:

   curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_arm64"
   chmod +x /usr/local/bin/wings
   

   Verify the installation:

   wings version
   

   You should see output similar to:

   wings v1.12.1
   Copyright © 2018 - 2026 Dane Everitt & Contributors
   
4. Configure Wings via Panel

   Wings provides an automatic configuration command that fetches settings from your Panel:

   Before running this command, create a node in your Pterodactyl Panel admin area and obtain the auto-configuration command from the node’s configuration tab.

   The command looks like this:

   wings configure --panel-url https://panel.example.com \
     --token YOUR_API_TOKEN \
     --node NODE_ID
   

   Parameters explained:

   • --panel-url (-p): Your Panel’s URL (must be accessible from Wings)
   • --token (-t): API token from the Panel
   • --node (-n): The numeric ID of the node

   This command will:

   1. Connect to your Panel via the API
   2. Fetch the node configuration
   3. Write the configuration to /etc/pterodactyl/config.yml

   Interactive Mode

   # Run without arguments for interactive prompts
   wings configure
   # You'll be prompted for Panel URL, Token, and Node ID
   

   # Provide all arguments directly
   wings configure \
     --panel-url https://panel.example.com \
     --token ptlc_abc123xyz789 \
     --node 1
   

   # Specify a custom configuration file location
   wings configure \
     --config-path /custom/path/config.yml \
     --panel-url https://panel.example.com \
     --token ptlc_abc123xyz789 \
     --node 1
   

   If you need to reconfigure an existing Wings installation, use the --override flag to overwrite the existing configuration file.

5. Start Wings in Debug Mode (Optional)

   Before setting up Wings as a service, test that it works correctly:

   # Start Wings in debug mode
   wings --debug
   

   You should see output similar to:

                     ____
   __ Pterodactyl _____/___/_______ _______ ______
   \_____\    \/\/    /   /       /  __   /   ___/
   \___\          /   /   /   /  /_/  /___   /
        \___/\___/___/___/___/___    /______/
                            /_______/ v1.12.1
   
   Copyright © 2018 - 2026 Dane Everitt & Contributors
   

   Wings will:

   • Load the configuration from /etc/pterodactyl/config.yml
   • Configure the Docker environment
   • Start the HTTP API server (default port 8080)
   • Start the SFTP server (default port 2022)
   • Load and initialize any existing servers

   Watch the logs to ensure there are no errors. Press Ctrl+C to stop Wings when you’re ready to continue.

6. Create Systemd Service

   Create a systemd service file to manage Wings:

   Create /etc/systemd/system/wings.service:

   [Unit]
   Description=Pterodactyl Wings Daemon
   After=docker.service
   Requires=docker.service
   PartOf=docker.service
   
   [Service]
   User=root
   WorkingDirectory=/etc/pterodactyl
   LimitNOFILE=4096
   PIDFile=/var/run/wings/daemon.pid
   ExecStart=/usr/local/bin/wings
   Restart=on-failure
   StartLimitInterval=180
   StartLimitBurst=30
   RestartSec=5s
   
   [Install]
   WantedBy=multi-user.target
   

   Enable and start the service:

   # Reload systemd to recognize the new service
   systemctl daemon-reload
   
   # Enable Wings to start on boot
   systemctl enable wings
   
   # Start Wings
   systemctl start wings
   

   Wings runs as root by default because it needs to interact with Docker and manage file permissions. The actual game servers run as the pterodactyl user inside containers.

7. Verify Wings is Running

   Check that Wings is running correctly:

   # Check service status
   systemctl status wings
   

   You should see:

   ● wings.service - Pterodactyl Wings Daemon
      Loaded: loaded (/etc/systemd/system/wings.service; enabled)
      Active: active (running) since ...
   

   View live logs:

   # Follow Wings logs in real-time
   journalctl -u wings -f
   

   Check that Wings is listening on the correct ports:

   # Check API port (default 8080)
   ss -tlnp | grep 8080
   
   # Check SFTP port (default 2022)
   ss -tlnp | grep 2022
   

Configure Firewall

Ensure your firewall allows traffic on the required ports:

UFW (Ubuntu/Debian)

# Allow Wings API (from Panel)
ufw allow 8080/tcp

# Allow SFTP
ufw allow 2022/tcp

# Allow game server ports (example range)
ufw allow 25565:25665/tcp
ufw allow 25565:25665/udp

# Allow Wings API
firewall-cmd --permanent --add-port=8080/tcp

# Allow SFTP
firewall-cmd --permanent --add-port=2022/tcp

# Allow game server ports
firewall-cmd --permanent --add-port=25565-25665/tcp
firewall-cmd --permanent --add-port=25565-25665/udp

# Reload firewall
firewall-cmd --reload

# Allow Wings API
iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

# Allow SFTP
iptables -A INPUT -p tcp --dport 2022 -j ACCEPT

# Save rules (Ubuntu/Debian)
netfilter-persistent save

The Wings API port (8080) should only be accessible from your Pterodactyl Panel server, not from the public internet. Configure your firewall accordingly.

Create Your First Server

With Wings running, you can now create servers from your Pterodactyl Panel:

1. Verify Node Connection

   In the Panel admin area, navigate to Nodes and check that your node shows as online with a green indicator.

2. Create a Server

   Go to Servers → Create New Server in the Panel and:

   • Select your Wings node
   • Choose an egg (game/application type)
   • Allocate resources (CPU, memory, disk)
   • Assign network allocations (IP and ports)
3. Install the Server

   The Panel will send installation instructions to Wings. Wings will:

   • Create a Docker container for the server
   • Run the installation script defined in the egg
   • Download game files as needed
   • Configure the server environment

   Monitor the installation in real-time via the server console in the Panel.

4. Start the Server

   Once installation completes, start the server from the Panel. Wings will:

   • Start the Docker container
   • Execute the startup command
   • Begin streaming console output
   • Report resource usage back to the Panel

Common Commands

Useful Wings commands for system administration:

Service Management

# Start Wings
systemctl start wings

# Stop Wings
systemctl stop wings

# Restart Wings
systemctl restart wings

# View status
systemctl status wings

# Enable autostart
systemctl enable wings

# Disable autostart
systemctl disable wings

# View recent logs
journalctl -u wings

# Follow logs in real-time
journalctl -u wings -f

# View logs since last boot
journalctl -u wings -b

# View logs from last hour
journalctl -u wings --since "1 hour ago"

# Check version
wings version

# Run in foreground (debug)
wings --debug

# Reconfigure from Panel
wings configure --override

# Run diagnostics
wings diagnostics

# Use custom config file
wings --config /custom/path/config.yml

Troubleshooting

Wings won't start

Common causes:

• Docker is not running: systemctl status docker
• Configuration file is missing or invalid: Check /etc/pterodactyl/config.yml
• Port already in use: Check with ss -tlnp | grep 8080
• Permission issues: Ensure Wings has access to required directories

Check logs for specific errors:

journalctl -u wings -n 50

Node shows offline in Panel

Verify:

• Wings service is running: systemctl status wings
• API port (8080) is accessible from Panel server
• Panel URL in config matches your actual Panel URL
• Authentication token is correct in /etc/pterodactyl/config.yml
• Firewall rules allow Panel → Wings communication

Servers won't start

Check:

• Docker containers: docker ps -a
• Server logs in Panel console
• Wings logs: journalctl -u wings -f
• Available system resources (memory, disk)
• Docker network configuration: docker network ls

Manually inspect container:

docker logs <container-name>
docker inspect <container-name>

SFTP connection fails

Verify:

• SFTP server is running on port 2022: ss -tlnp | grep 2022
• Firewall allows port 2022
• Using correct credentials (Panel username and password)
• Server is not suspended
• SFTP is not disabled in config: Check read_only setting

Test SFTP connection:

sftp -P 2022 username@your-wings-server

Next Steps

Now that Wings is running, explore these topics:

Configuration

Customize Wings behavior and settings

SSL/TLS Setup

Enable HTTPS with Let’s Encrypt

Performance Tuning

Optimize Wings for your workload

Backup Operations

Configure automated backups

Additional Resources

For more detailed information, consult the following resources:

• Official Wings Documentation
• Community Guides
• GitHub Issues
• Discord Support