> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pterodactyl/panel/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  Always restart Wings after making configuration changes: `systemctl restart wings`
</Warning>

## Complete Configuration Example

```yaml /etc/pterodactyl/config.yml theme={null}
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

```yaml theme={null}
debug: false
```

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

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

### Node Authentication

```yaml theme={null}
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)

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

## API Configuration

### Host and Port

```yaml theme={null}
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)

<Note>
  If changing the port, update your Panel's node configuration and firewall rules accordingly.
</Note>

### SSL/TLS

```yaml theme={null}
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

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

### Upload Limit

```yaml theme={null}
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:

```yaml theme={null}
api:
  upload_limit: 500  # Allow 500MB uploads
```

## System Configuration

### Directories

```yaml theme={null}
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

<Tip>
  Use a separate disk or partition for `root_directory` to prevent servers from filling up the system disk.
</Tip>

### SFTP Configuration

```yaml theme={null}
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:

```bash theme={null}
sftp -P 2022 username.serverid@node.example.com
```

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

### Timezone

```yaml theme={null}
system:
  timezone: UTC
```

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

```yaml theme={null}
system:
  timezone: America/New_York
```

### System User

```yaml theme={null}
system:
  username: pterodactyl
```

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

### Rootless Containers

```yaml theme={null}
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

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

## Concurrency Settings

### Backup Concurrency

```yaml theme={null}
system:
  backup_concurrency: 2
```

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

Increase on high-performance nodes:

```yaml theme={null}
system:
  backup_concurrency: 4  # Allow 4 simultaneous backups
```

### Transfer Concurrency

```yaml theme={null}
system:
  transfer_concurrency: 2
```

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

## Remote Panel URL

```yaml theme={null}
remote: https://panel.example.com
```

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

<Warning>
  This URL must exactly match your Panel's configured URL. Include the protocol (https\://) and exclude trailing slashes.
</Warning>

## Allowed Mounts

```yaml theme={null}
allowed_mounts:
  - /mnt/shared-data
  - /opt/game-configs
```

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

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

Example for read-only shared configs:

```yaml theme={null}
allowed_mounts:
  - /opt/shared-configs
```

Then configure the mount in the Panel as:

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

## Allowed Origins

```yaml theme={null}
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:

```yaml theme={null}
allowed_origins:
  - https://panel.example.com
```

## Console Throttles

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

```yaml theme={null}
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

<Tip>
  Increase `lines` if legitimate servers are being throttled during startup:

  ```yaml theme={null}
  throttles:
    lines: 5000  # Allow more output
  ```
</Tip>

## Environment Variables

You can override certain config values with environment variables:

```bash /etc/systemd/system/wings.service theme={null}
[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:

```bash theme={null}
# Test configuration
wings configure --check

# Test Wings startup
wings --debug
```

## Common Configurations

### High-Performance Node

```yaml theme={null}
api:
  upload_limit: 500

system:
  backup_concurrency: 4
  transfer_concurrency: 3

throttles:
  enabled: true
  lines: 5000
```

### Secure Production Node

```yaml theme={null}
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

```yaml theme={null}
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:

<Steps>
  <Step title="Edit config file">
    ```bash theme={null}
    nano /etc/pterodactyl/config.yml
    ```
  </Step>

  <Step title="Validate changes">
    ```bash theme={null}
    wings configure --check
    ```
  </Step>

  <Step title="Restart Wings">
    ```bash theme={null}
    systemctl restart wings
    ```
  </Step>

  <Step title="Verify status">
    ```bash theme={null}
    systemctl status wings
    journalctl -u wings -n 50
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Docker Management" icon="docker" href="/wings/docker-management">
    Learn how Wings manages containers
  </Card>

  <Card title="Networking" icon="network-wired" href="/wings/networking">
    Configure networking and ports
  </Card>

  <Card title="Security" icon="shield" href="/wings/security">
    Secure your Wings installation
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/wings/monitoring">
    Monitor Wings performance
  </Card>
</CardGroup>