LocalAI Monitor - Home Assistant Integration

A Home Assistant custom integration for monitoring LocalAI instances. Track installed models, backends, system resources, and manage running models directly from Home Assistant.

NOTE: This is not for monitoring a "local AI", this is specifically for the product called "LocalAI", available from https://localai.io

Features

• Model Monitoring: Track all installed models with detailed information including:

  • Runtime status (Running, Idle)

• Backend Tracking: Monitor installed backends and their metadata

• System Monitoring: Track system information and resource usage

• Model Management: Shutdown running models to free up resources via Home Assistant services

• Jobs Monitoring: Track model loading and processing jobs

Installation

HACS (Recommended)

1. Add this repository as a custom repository in HACS:

   • Go to HACS → Integrations → ⋮ (menu) → Custom repositories
   • Add: https://github.com/loryanstrant/HA-LocalAI-Monitor
   • Category: Integration

2. Click "Download" on the LocalAI Monitor integration

3. Restart Home Assistant

4. Go to Settings → Devices & Services → Add Integration

5. Search for "LocalAI Monitor"

Manual Installation

1. Copy the custom_components/localai_monitor folder to your Home Assistant custom_components directory
2. Restart Home Assistant
3. Go to Settings → Devices & Services → Add Integration
4. Search for "LocalAI Monitor"

Configuration

Configure the integration through the UI:

• URL: Your LocalAI instance URL (e.g., http://localhost:8080)
• API Key: (Optional) Your LocalAI API key if authentication is enabled
• Verify SSL: Whether to verify SSL certificates
• Scan Interval: How often to poll LocalAI for updates (default: 60 seconds)

Sensors

The integration provides the following sensors:

Installed Models

• State: Number of installed models
• Attributes: List of models with running/idle status (derived from /system loaded models)

Running Models

• State: Number of currently loaded (running) models
• Attributes: List of running models, each enriched with:
  • backend — the backend serving the model (e.g. llama-cpp, vllm, whisper), resolved from the model's config
  • vram_estimate_bytes / vram_estimate_gb / vram_estimate_display — estimated VRAM the model uses while loaded
  • context_length — context size used for the estimate
  • state / memory_bytes / memory_gb — live backend process state and memory, when the backend implements the status RPC (best effort; absent for backends that don't, e.g. llama-cpp)
• Also exposes backends_in_use (the distinct backends across all running models) and total_estimated_vram_gb (sum of the per-model estimates).

Note on VRAM: LocalAI does not expose measured per-model VRAM for most backends, so the per-model figure is an estimate derived from the model config. Measured, server-wide GPU/VRAM usage is available on the Resources sensor.

Installed Backends

• State: Number of installed backends
• Attributes: List of backends with installation metadata

System

• State: System status
• Attributes: System information from LocalAI

Resources

• State: Resource status
• Attributes: Resource usage information

Model Jobs

• State: Number of active jobs
• Attributes: List of running model jobs

Services

localai_monitor.shutdown_model

Shut down a specific model to free up resources.

Parameters:

• model_name (required): The name of the model to shut down (e.g., "gpt-4", "llama3-instruct")

Example:

service: localai_monitor.shutdown_model
data:
  model_name: "gpt-4"

Use Cases

Automation Example: Shutdown Idle Models

automation:
  - alias: "Shutdown idle LocalAI models at night"
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: localai_monitor.shutdown_model
        data:
          model_name: "gpt-4"

Dashboard Example

Display model information in your dashboard:

type: entities
entities:
  - entity: sensor.localai_monitor_installed_models
    name: Models
  - entity: sensor.localai_monitor_installed_backends
    name: Backends
  - entity: sensor.localai_monitor_system
    name: System Status

Technical Details

• Model Information Source: Model running/idle status is determined via the /system API endpoint (loaded_models field), which replaced the previously used /manage HTML page that was removed in LocalAI v4.x.
• API Endpoints Used:
  • /v1/models - Model list
  • /backends - Backend information
  • /models/jobs - Job status
  • /system - System information (including loaded/running models)
  • /api/resources - Resource usage
  • /backend/shutdown - Model shutdown endpoint
  • /backend/monitor - Backend monitor (query parameter form, fixed in LocalAI v4.2.0)

Requirements

• Home Assistant 2025.10.0 or newer
• LocalAI v4.2.0 or newer (confirmed working with v4.2.4+)

Compatibility

This integration (v1.3.0+) requires LocalAI v4.2.0 or newer. Earlier versions of LocalAI included a /manage page that was used for model detail enrichment; this page was removed in v4.x. The integration now uses only the stable REST API endpoints.

If you are running an older version of LocalAI, use integration version 1.2.0 or earlier.

Support

For issues, feature requests, or contributions, please visit the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Development Approach

Disclaimer

This integration is in no way affiliated with LocalAI, but created out of appreciation.