Update Configuration

Update the runtime configuration of a Wings instance from the Pterodactyl Panel

Endpoint

POST /api/update

Updates the running configuration for the Wings instance. This endpoint allows the Pterodactyl Panel to push configuration updates to Wings without requiring a restart. The new configuration is validated, written to disk, and applied to the running instance.

Authentication

This endpoint requires authentication using a Bearer token in the Authorization header.

Authorization: Bearer <your-token>

Request Body

The request body should contain a complete Wings configuration object in JSON format. This follows the same structure as the config.yml file.

debug · boolean

Enable debug mode for verbose logging

app_name · string · default: "Pterodactyl"

Application name for Wings

uuid · string · required

Unique identifier for this node in the Panel

token_id · string · required

Token identifier for authentication

token · string · required

Authentication token for API requests

api · object · required

API server configuration

Show api properties

api.host · string · default: "0.0.0.0"

Host address to bind the API server to

api.port · integer · default: "8080"

Port to bind the API server to

api.ssl · object

SSL/TLS configuration

Show ssl properties

api.ssl.enabled · boolean

Enable SSL/TLS

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

api.trusted_proxies · array

List of trusted proxy IP addresses

api.disable_remote_download · boolean

Disable remote file download functionality

system · object · required

System configuration settings

Show system properties

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

Root directory for all Pterodactyl data

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

Directory for Wings logs

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

Directory for server data

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 server backups

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

Temporary directory for Wings operations

system.username · string · default: "pterodactyl"

System user that owns server files

system.timezone · string

Timezone for containers (auto-detected if not set)

docker · object · required

Docker configuration settings (see Docker Settings for details)

remote · string · required

Panel URL for API communication

remote_query · object

Remote query configuration

Show remote_query properties

remote_query.timeout · integer · default: "30"

Request timeout in seconds for Panel API calls

remote_query.boot_servers_per_page · integer · default: "50"

Number of servers to load per request during boot

allowed_mounts · array

List of allowed host paths for server mounts

allowed_origins · array

Additional CORS allowed origins

ignore_panel_config_updates · boolean · default: "false"

When enabled, configuration updates from the Panel are ignored

Response

applied · boolean

Indicates whether the configuration update was applied. Returns false if ignore_panel_config_updates is enabled in the current configuration.

Behavior

Configuration Update Flow

1. Validation: The incoming configuration is validated and merged with defaults
2. SSL Certificate Handling: If SSL certificates use Let’s Encrypt default paths (/etc/letsencrypt/live/), the existing certificate paths are preserved to prevent overwriting manually configured locations
3. Disk Write: The configuration is written to disk at the config file location
4. Runtime Update: If the write succeeds, the global configuration state is updated
5. Response: Returns whether the update was applied

Ignored Updates

When ignore_panel_config_updates is set to true in the Wings configuration file, this endpoint will:

• Return {"applied": false}
• Not write any changes to disk
• Not update the runtime configuration

This is useful for Wings instances that need to maintain custom configurations independent of Panel updates.

Configuration updates are applied immediately to the running Wings instance without requiring a restart. However, some changes (like port bindings) may not take full effect until Wings is restarted.

Example Requests

cURL

curl -X POST "https://wings.example.com/api/update" \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "3e3e4e5e-6f7f-8a8a-9b9b-0c0c0d0d0e0e",
    "token_id": "abc123",
    "token": "your-authentication-token",
    "api": {
      "host": "0.0.0.0",
      "port": 8080,
      "ssl": {
        "enabled": true,
        "cert": "/etc/letsencrypt/live/wings.example.com/fullchain.pem",
        "key": "/etc/letsencrypt/live/wings.example.com/privkey.pem"
      },
      "upload_limit": 100
    },
    "system": {
      "root_directory": "/var/lib/pterodactyl",
      "data": "/var/lib/pterodactyl/volumes",
      "username": "pterodactyl"
    },
    "remote": "https://panel.example.com"
  }'

const config = {
  uuid: '3e3e4e5e-6f7f-8a8a-9b9b-0c0c0d0d0e0e',
  token_id: 'abc123',
  token: 'your-authentication-token',
  api: {
    host: '0.0.0.0',
    port: 8080,
    ssl: {
      enabled: true,
      cert: '/etc/letsencrypt/live/wings.example.com/fullchain.pem',
      key: '/etc/letsencrypt/live/wings.example.com/privkey.pem'
    },
    upload_limit: 100
  },
  system: {
    root_directory: '/var/lib/pterodactyl',
    data: '/var/lib/pterodactyl/volumes',
    username: 'pterodactyl'
  },
  remote: 'https://panel.example.com'
};

const response = await fetch('https://wings.example.com/api/update', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(config)
});

const result = await response.json();
console.log('Configuration applied:', result.applied);

import requests

config = {
    'uuid': '3e3e4e5e-6f7f-8a8a-9b9b-0c0c0d0d0e0e',
    'token_id': 'abc123',
    'token': 'your-authentication-token',
    'api': {
        'host': '0.0.0.0',
        'port': 8080,
        'ssl': {
            'enabled': True,
            'cert': '/etc/letsencrypt/live/wings.example.com/fullchain.pem',
            'key': '/etc/letsencrypt/live/wings.example.com/privkey.pem'
        },
        'upload_limit': 100
    },
    'system': {
        'root_directory': '/var/lib/pterodactyl',
        'data': '/var/lib/pterodactyl/volumes',
        'username': 'pterodactyl'
    },
    'remote': 'https://panel.example.com'
}

response = requests.post(
    'https://wings.example.com/api/update',
    headers={'Authorization': 'Bearer your-token-here'},
    json=config
)

result = response.json()
print(f"Configuration applied: {result['applied']}")

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type Config struct {
    UUID    string         `json:"uuid"`
    TokenID string         `json:"token_id"`
    Token   string         `json:"token"`
    API     map[string]any `json:"api"`
    System  map[string]any `json:"system"`
    Remote  string         `json:"remote"`
}

func main() {
    config := Config{
        UUID:    "3e3e4e5e-6f7f-8a8a-9b9b-0c0c0d0d0e0e",
        TokenID: "abc123",
        Token:   "your-authentication-token",
        Remote:  "https://panel.example.com",
    }
    
    jsonData, _ := json.Marshal(config)
    req, _ := http.NewRequest("POST", "https://wings.example.com/api/update", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer your-token-here")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result map[string]bool
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Configuration applied: %v\n", result["applied"])
}

Example Responses

Success - Applied

{
  "applied": true
}

{
  "applied": false
}

Error Responses

400 Bad Request

{
  "error": "Invalid JSON payload"
}

{
  "error": "Unauthorized"
}

{
  "error": "Failed to write configuration to disk"
}

SSL Certificate Handling

The endpoint includes special logic for SSL certificates to prevent accidental overwrites:

// If the Panel sends Let's Encrypt default paths
if (config.api.ssl.key.startsWith('/etc/letsencrypt/live/')) {
  // Wings preserves existing custom certificate paths
  // This prevents overwriting manually configured SSL certificates
}

If you need to update SSL certificate paths, ensure they don’t use the default Let’s Encrypt location pattern, or manually update the configuration file.

Use Cases

Automated Panel Updates

The Pterodactyl Panel automatically calls this endpoint when node configuration is updated:

def update_node_configuration(node_id, new_config):
    """Called by Panel when admin updates node settings"""
    response = requests.post(
        f'https://{node.fqdn}:{node.port}/api/update',
        headers={'Authorization': f'Bearer {node.daemon_token}'},
        json=new_config
    )
    
    if response.json()['applied']:
        print(f'Configuration updated for node {node_id}')
    else:
        print(f'Node {node_id} is ignoring Panel configuration updates')

Manual Configuration Sync

You can manually sync configuration from your Panel to Wings:

#!/bin/bash
# Sync Wings configuration from Panel

curl -X POST "https://wings.example.com/api/update" \
  -H "Authorization: Bearer $(cat /etc/pterodactyl/config.yml | grep '^token:' | awk '{print $2}')" \
  -H "Content-Type: application/json" \
  -d @/tmp/new-config.json

Implementation Details

The configuration update process is implemented in router/router_system.go:122-158:

1. Check ignore flag: If IgnorePanelConfigUpdates is true, return {"applied": false} immediately
2. Parse JSON: Bind the incoming JSON to a Configuration struct
3. Preserve SSL paths: Check for Let’s Encrypt default paths and preserve existing custom paths
4. Write to disk: Call config.WriteToDisk() to persist the new configuration
5. Update runtime: Call config.Set() to apply changes to the running instance
6. Return result: Return {"applied": true} on success

The configuration file location is determined by the --config flag used when starting Wings. By default, this is /etc/pterodactyl/config.yml.

Security Considerations

This endpoint can modify critical Wings configuration. Ensure your authentication token is kept secure and only accessible by the Pterodactyl Panel.

• The endpoint requires a valid Bearer token matching the configured AuthenticationToken
• Configuration changes are written to disk with restricted file permissions
• Invalid configurations will cause the request to fail without modifying the existing config
• SSL certificate paths are validated and protected from accidental overwrites

Related Endpoints

• Get System Information - Retrieve system and Wings version information
• Get Servers - List all servers managed by this Wings instance

Related Configuration

• Configuration File - Complete configuration file reference
• System Settings - System configuration options
• SSL/TLS Configuration - SSL certificate setup