Skip to main content

​
What is Wings?

Wings is Pterodactyl’s server control plane, built for the rapidly changing gaming industry and designed to be highly performant and secure. It provides an HTTP API that allows you to interface directly with running server instances, fetch server logs, generate backups, and control all aspects of the server lifecycle.
Wings works in conjunction with the Pterodactyl Panel to provide a complete game server management solution. The Panel provides the web interface while Wings handles the actual server process management.

​
Key Features

Wings provides a comprehensive set of features for managing game servers:

​
Docker-Based Container Management

Wings leverages Docker to provide isolated, secure environments for each game server. Each server runs in its own container with:
  • Resource Limits: Memory and CPU limits configurable per server
  • Network Isolation: Custom network configuration with configurable DNS and networking
  • Process Control: Full lifecycle management (start, stop, restart, kill)
  • Environment Variables: Dynamic environment configuration passed to containers
config/config.go
// Container resource limits are enforced at the Docker level
ContainerPidLimit int64 `default:"512"`
TmpfsSize uint `default:"100"` // Size for /tmp in MB

​
Built-in SFTP Server

Wings ships with a built-in SFTP server that:
  • Allows users to access server files without SSH access to the host
  • Authenticates using the same credentials as the Panel
  • Eliminates the need for Pterodactyl-specific dependencies on the host system
  • Provides secure file transfer capabilities
system:
  sftp:
    bind_address: 0.0.0.0
    bind_port: 2022
    read_only: false

​
Real-time WebSocket Communication

Wings provides WebSocket endpoints for real-time server interaction:
  • Console Output: Stream server console logs in real-time
  • Resource Statistics: CPU, memory, disk, and network usage
  • Power Actions: Execute commands and control server state
  • File Operations: Real-time file system operations

​
HTTP API for Server Control

The Wings HTTP API exposes endpoints for comprehensive server management at cmd/root.go:48: 
// Available power actions
PowerActionStart   = "start"
PowerActionStop    = "stop" 
PowerActionRestart = "restart"
PowerActionKill    = "kill"

​
Advanced File Management

Wings provides a custom filesystem implementation (server/filesystem/filesystem.go) with:
  • Path Validation: Prevents directory traversal attacks
  • Disk Quotas: Enforces per-server storage limits
  • Compression: Create and extract archives (tar.gz, zip)
  • Permissions: Automatic file ownership management
  • Bulk Operations: Copy, move, and delete multiple files

​
Backup & Transfer System

Wings includes built-in backup functionality:
  • Local Backups: Store backups on the Wings server
  • S3-Compatible Storage: Upload backups to remote storage
  • Server Transfers: Migrate servers between Wings nodes
  • Compression Control: Configurable compression levels
  • Write Limits: Throttle I/O to prevent system impact
system:
  backups:
    write_limit: 0  # MB/s (0 = unlimited)
    compression_level: best_speed  # or best_compression

​
Crash Detection & Recovery

Wings automatically monitors server processes at server/crash.go:
  • Automatic Detection: Identifies unexpected server crashes
  • Smart Recovery: Attempts automatic restart with configurable thresholds
  • Clean Exit Detection: Optionally treats clean exits as crashes
  • Boot Loop Prevention: Prevents infinite restart cycles
config.yml
system:
  crash_detection:
    enabled: true
    detect_clean_exit_as_crash: true
    timeout: 60  # seconds between crashes

​
Resource Monitoring

Wings continuously tracks server resource usage (environment/stats.go):
  • CPU Usage: Real-time CPU percentage
  • Memory: Current memory consumption and limits
  • Disk Space: Storage usage with quota enforcement
  • Network I/O: Inbound and outbound traffic statistics

​
Architecture Overview

Wings is built with Go and follows a modular architecture: 
Wings Architecture
├── HTTP API Server (port 8080)
│   ├── RESTful endpoints for Panel communication
│   ├── WebSocket server for real-time connections
│   └── File upload/download handlers
│
├── SFTP Server (port 2022)
│   ├── Authentication via Panel API
│   └── Isolated file system access per server
│
├── Server Manager
│   ├── Server lifecycle management
│   ├── Configuration synchronization
│   └── State persistence
│
├── Docker Environment
│   ├── Container creation and management
│   ├── Resource limit enforcement
│   └── Network configuration
│
└── Background Workers
    ├── Resource usage collection
    ├── Activity log aggregation
    └── Backup processing

​
How Wings Fits into Pterodactyl

Pterodactyl uses a distributed architecture:
1

Panel (Web Interface)

The Pterodactyl Panel provides the web-based management interface where users and administrators interact with servers. It handles:
  • User authentication and permissions
  • Server allocation and configuration
  • Billing and resource management
  • Egg (game configuration) management
2

Wings (Control Plane)

Wings runs on each physical or virtual server (node) and handles:
  • Actual server process execution
  • Real-time resource monitoring
  • File system operations
  • Console access and command execution
3

Communication Flow

The Panel and Wings communicate via secure HTTP API:
User → Panel (HTTPS) → Wings (API) → Docker → Game Server
Wings reports server state and statistics back to the Panel for display to users.
Wings requires Docker to be installed and running on the host system. All game servers run as Docker containers managed by Wings.

​
System Requirements

To run Wings effectively, your system should meet these requirements:
  • Operating System: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+, or similar)
  • Docker: Version 20.10 or newer
  • Architecture: x86_64 (amd64) or ARM64
  • Memory: Minimum 1GB available (plus memory for game servers)
  • Disk Space: Depends on number and size of game servers
  • Network: Open ports 8080 (API) and 2022 (SFTP), plus game server ports

​
Security Considerations

Wings implements multiple security layers:
  • Authentication: All API requests require valid Panel-issued tokens at config/config.go:318
  • Path Validation: Filesystem operations prevent directory traversal
  • Container Isolation: Each server runs in an isolated Docker container
  • TLS Support: Optional HTTPS with automatic Let’s Encrypt certificates
  • Resource Limits: Per-server CPU, memory, and disk quotas
cmd/root.go:84
// Wings supports automatic TLS via Let's Encrypt
rootCommand.Flags().Bool("auto-tls", false, 
    "generate and manage SSL certificates using Let's Encrypt")
rootCommand.Flags().String("tls-hostname", "", 
    "FQDN for the generated SSL certificate")

​
Next Steps

Quick Start

Get Wings up and running in minutes

Configuration

Learn about Wings configuration options

API Reference

Explore the Wings HTTP API

Core Concepts

Understand Wings architecture

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us