# How CasaOS Monitors System Health and Updates Hardware Status: A Deep Dive into the Go Implementation

> Discover how CasaOS monitors system health and hardware status with its Go implementation. Learn about the HealthService SystemService gopsutil and REST API.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: deep-dive
- Published: 2026-06-27

---

**CasaOS monitors system health and hardware status through a layered architecture that combines Go-based services (`HealthService` and `SystemService`), the gopsutil library, and REST API endpoints exposed via [`route/v1/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/system.go) and [`route/v2/health.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/health.go).**

The open-source CasaOS project by IceWhaleTech provides a lightweight home cloud OS that requires real-time visibility into host health and hardware components. Understanding how CasaOS monitors system health and updates hardware status reveals a clean separation between data collection services and HTTP API layers. This implementation leverages native Go libraries alongside system utilities to expose CPU metrics, memory usage, disk statistics, and service states through structured JSON endpoints.

## HealthService Implementation

The **HealthService** interface, defined in [`service/health.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/health.go), focuses on software-level health by tracking CasaOS-related systemd services and network port utilization.

### Monitoring CasaOS Services

The `Services()` method queries the host's systemd state to distinguish between running and stopped CasaOS components. It invokes `systemctl.ListServices("casaos*")` from the `pkg/utils/systemctl` package in CasaOS-Common, returning a map that categorizes service names by their boolean state.

### Tracking Network Ports

To identify port conflicts, the `Ports()` method forwards calls to `port.ListPortsInUse()` from the `pkg/utils/port` utility in CasaOS-Common. This returns a slice of integers representing occupied TCP and UDP ports currently in use by the system.

## SystemService Hardware Monitoring

The **SystemService** in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go) provides comprehensive hardware introspection using the **gopsutil** library supplemented by direct `/sys` filesystem reads and helper scripts.

### CPU Metrics and Temperature

CPU data collection relies on multiple gopsutil wrappers and system file parsing:

- `GetCpuInfo()` returns processor model and architecture details via `cpu.InfoStat`
- `GetCpuPercent()` and `GetCpuCoreNum()` provide utilization percentages and core counts
- `GetCPUTemperature()` reads thermal-zone data or `/sys` class files to return current temperature in Celsius
- `GetCPUPower()` extracts energy consumption values (in µJ) from specific `/sys` filesystem paths, returning a map with `value` and `timestamp` fields

### Memory and Disk Utilization

Memory statistics come from `GetMemInfo()`, which wraps `mem.VirtualMemory()` to return total, available, and used memory metrics along with usage percentages. For storage, `GetDiskInfo()` calls `disk.Usage("/")` to report root filesystem capacity and consumption.

### Network Interface Statistics

Network monitoring uses `GetNetInfo()`, `GetNet()`, and `GetNetState()` to aggregate interface counters. These methods invoke `net.IOCounters` from gopsutil and execute helper scripts to determine link states and transfer statistics for all network interfaces.

### Device Tree Discovery

Low-level hardware identification, such as drive model detection, executes through `GetDeviceTree()`. This method runs the [`helper.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/helper.sh) script to parse system device trees, returning strings like "Samsung SSD 860" that identify specific storage hardware.

## REST API Endpoints

CasaOS exposes collected metrics through versioned HTTP routes that serialize Go structs into JSON for frontend consumption.

### Hardware Information Endpoint

The `GET /sys/hardware/info` handler in [`route/v1/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/system.go) aggregates data by calling `service.MyService.System().GetDeviceTree()` and `runtime.GOARCH`. This endpoint returns a unified payload containing device tree information, CPU details, and system architecture.

### System Utilization Endpoint

The `GET /sys/utilization` endpoint constructs a comprehensive JSON response including CPU percent, core count, temperature, power consumption, memory statistics, disk usage, and network counters. All data originates from the `SystemService` methods defined in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go).

### Health Check Endpoint

Defined in [`route/v2/health.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/health.go) with mirrored functionality in v1, the health endpoint instantiates `NewHealthService()` to return the service state map and active port list. This allows the frontend to display which CasaOS services are alive and identify potential port conflicts.

## Practical Implementation Examples

The following Go patterns demonstrate how to interact with these services directly:

```go
// Retrieve running CasaOS services and used ports
svc := service.NewHealthService()
services, _ := svc.Services()          // map[bool]*[]string{true:running, false:stopped}
portsInUse, _, _ := svc.Ports()        // []int of occupied TCP/UDP ports

```

```go
// Get detailed hardware status (used by /sys/hardware/info)
sys := service.NewSystemService()
deviceTree := sys.GetDeviceTree()      // e.g. "Samsung SSD 860"
cpuInfo := sys.GetCpuInfo()            // []cpu.InfoStat
temp := sys.GetCPUTemperature()        // °C
power := sys.GetCPUPower()             // map[string]string{"value":"123456","timestamp":"..."}
mem := sys.GetMemInfo()                // map[string]interface{}{"total":..., "usedPercent":...}
disk := sys.GetDiskInfo()              // *disk.UsageStat
net := sys.GetNetInfo()                // []net.IOCountersStat

```

## Summary

- **HealthService** ([`service/health.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/health.go)) monitors CasaOS systemd services and network ports via `systemctl.ListServices()` and `port.ListPortsInUse()`.
- **SystemService** ([`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go)) collects hardware metrics using gopsutil for CPU, memory, disk, and network data, while reading `/sys` files directly for temperature and power consumption.
- **Device discovery** relies on [`helper.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/helper.sh) scripts executed through `GetDeviceTree()` to identify specific hardware models.
- **REST endpoints** in [`route/v1/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/system.go) and [`route/v2/health.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/health.go) expose all metrics through `GET /sys/hardware/info`, `GET /sys/utilization`, and health check routes.

## Frequently Asked Questions

### How does CasaOS read CPU temperature without external sensors?

CasaOS reads CPU temperature through the `GetCPUTemperature()` method in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go), which parses thermal-zone files or specific `/sys` class paths to return values in Celsius. This approach requires no external hardware sensors, relying instead on kernel-exposed thermal interfaces available on Linux systems.

### What library handles system metrics in CasaOS?

CasaOS uses the **gopsutil** Go library to collect system metrics. This library provides cross-platform functions for CPU info (`cpu.InfoStat`), memory statistics (`mem.VirtualMemory()`), disk usage (`disk.Usage()`), and network counters (`net.IOCounters`), which the `SystemService` wraps and normalizes into Go structs.

### How does CasaOS determine which services are currently running?

The system determines running services through `HealthService.Services()` in [`service/health.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/health.go), which calls `systemctl.ListServices("casaos*")` from the CasaOS-Common library. This filters systemd services matching the "casaos" pattern and returns them categorized as running or stopped based on their current systemd state.

### Where does CasaOS get detailed hardware device information?

Detailed hardware information comes from `GetDeviceTree()` in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go), which executes the [`helper.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/helper.sh) script to parse system device trees and identify specific components like drive models. This complements the generic metrics from gopsutil with specific hardware identifiers necessary for the web UI display.