Get System Information

Retrieve comprehensive system information including Wings version, Docker details, and hardware specifications

Endpoint

GET /api/system

Returns detailed information about the system that Wings is running on, including Wings version, Docker configuration, container statistics, and hardware specifications.

Authentication

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

Authorization: Bearer <your-token>

Query Parameters

v · string

API version for the response format. Use "2" to receive the full detailed response. Without this parameter, a simplified legacy response is returned.

Response Formats

Version 2 Response (Recommended)

When using ?v=2, the endpoint returns comprehensive system information:

version · string

The current Wings version (e.g., "develop" or "v1.11.0")

docker · object

Docker-related information

Show docker properties

version · string

Docker daemon version

cgroups · object

Container cgroup configuration

Show cgroups properties

driver · string

Cgroup driver (e.g., "systemd", "cgroupfs")

version · string

Cgroup version (e.g., "1", "2")

containers · object

Container statistics

Show containers properties

total · integer

Total number of containers on the system

running · integer

Number of running containers

paused · integer

Number of paused containers

stopped · integer

Number of stopped containers

storage · object

Storage driver information

Show storage properties

driver · string

Storage driver being used (e.g., "overlay2", "aufs")

filesystem · string

Backing filesystem (e.g., "extfs", "xfs")

runc · object

RunC runtime information

Show runc properties

version · string

RunC commit ID/version

system · object

Host system information

Show system properties

architecture · string

System architecture (e.g., "amd64", "arm64")

cpu_threads · integer

Number of CPU threads available

memory_bytes · integer

Total system memory in bytes

kernel_version · string

Linux kernel version

os · string

Operating system description (e.g., "Ubuntu 22.04.3 LTS")

os_type · string

Operating system type (e.g., "linux")

Legacy Response (Default)

Without the v query parameter, a simplified response is returned for backward compatibility:

architecture · string

System architecture (e.g., "amd64")

cpu_count · integer

Number of CPU threads available

kernel_version · string

Linux kernel version

os · string

Operating system type (e.g., "linux")

version · string

Wings version

Example Requests

cURL (Version 2)

curl -X GET "https://wings.example.com/api/system?v=2" \
  -H "Authorization: Bearer your-token-here"

curl -X GET "https://wings.example.com/api/system" \
  -H "Authorization: Bearer your-token-here"

const response = await fetch('https://wings.example.com/api/system?v=2', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});

const systemInfo = await response.json();
console.log(systemInfo);

import requests

response = requests.get(
    'https://wings.example.com/api/system?v=2',
    headers={'Authorization': 'Bearer your-token-here'}
)

system_info = response.json()
print(system_info)

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://wings.example.com/api/system?v=2", nil)
    req.Header.Set("Authorization", "Bearer your-token-here")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Example Responses

Version 2 Response

{
  "version": "v1.11.0",
  "docker": {
    "version": "24.0.7",
    "cgroups": {
      "driver": "systemd",
      "version": "2"
    },
    "containers": {
      "total": 15,
      "running": 12,
      "paused": 0,
      "stopped": 3
    },
    "storage": {
      "driver": "overlay2",
      "filesystem": "extfs"
    },
    "runc": {
      "version": "1.1.10-0ubuntu1~22.04.1"
    }
  },
  "system": {
    "architecture": "amd64",
    "cpu_threads": 8,
    "memory_bytes": 16777216000,
    "kernel_version": "5.15.0-91-generic",
    "os": "Ubuntu 22.04.3 LTS",
    "os_type": "linux"
  }
}

{
  "architecture": "amd64",
  "cpu_count": 8,
  "kernel_version": "5.15.0-91-generic",
  "os": "linux",
  "version": "v1.11.0"
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

{
  "error": "Failed to retrieve system information"
}

Use Cases

Health Monitoring

This endpoint is useful for monitoring the health and status of your Wings installation:

async function checkSystemHealth() {
  const info = await fetch('https://wings.example.com/api/system?v=2', {
    headers: { 'Authorization': 'Bearer token' }
  }).then(r => r.json());
  
  // Check if Wings version is up to date
  console.log('Wings Version:', info.version);
  
  // Monitor Docker container stats
  const containerUsage = info.docker.containers.running / info.docker.containers.total;
  console.log(`Container Usage: ${(containerUsage * 100).toFixed(1)}%`);
  
  // Check available resources
  const memoryGB = info.system.memory_bytes / (1024 ** 3);
  console.log(`Total Memory: ${memoryGB.toFixed(2)} GB`);
}

Compatibility Checks

Verify that the system meets requirements before deploying servers:

def verify_system_requirements(system_info):
    # Check cgroup version for proper container management
    if system_info['docker']['cgroups']['version'] != '2':
        print('Warning: cgroup v2 recommended for optimal performance')
    
    # Verify storage driver
    if system_info['docker']['storage']['driver'] != 'overlay2':
        print('Warning: overlay2 storage driver recommended')
    
    # Check available CPU cores
    if system_info['system']['cpu_threads'] < 4:
        print('Warning: At least 4 CPU threads recommended')

Implementation Details

The system information is gathered from multiple sources:

• Wings Version: Read from system.Version constant in system/const.go
• Docker Information: Retrieved via Docker API using client.ServerVersion() and client.Info()
• System Details: Collected using Go’s runtime package and /etc/os-release file
• Kernel Version: Parsed from Docker’s kernel detection utilities

The endpoint returns live data from the system and Docker daemon. For frequently updated monitoring, consider caching responses appropriately to reduce load.

Related Endpoints

• Update Configuration - Update Wings runtime configuration
• Get Servers - List all servers managed by this Wings instance