Install • Configuration • API

A lightweight service that exposes system metrics via an HTTP API,
intended to be used with Glance's server stats widget

Choose one of the following methods:

services:
  glance-agent:
    container_name: glance-agent
    image: glanceapp/agent
    environment:
      # Optional, leave empty or comment out for no authentication
      TOKEN: your_auth_token_here
    volumes:
      # Add your mount points below in the format host_path:container_path with :ro suffix for read-only
      - /storage:/storage:ro
    ports:
      - 27973:27973

- type: remote
  name: Custom Server Name
  url: http://<server IP or domain>:27973
  token: <token from above, if set>

Automatic installation as a systemd service

Download the latest release for your architecture from the releases page, extract it, then run:

sudo ./agent install

And follow the instructions. When done, the agent can later be configured through the config file at:

/opt/glance-agent/agent.yml

(default location unless changed during installation)

Service must be restarted after making changes to the config file.

Demo

[!NOTE]

To update the agent, you must download the latest release and replace the existing binary at /opt/glance-agent/agent. Then, restart the service with:

sudo systemctl restart glance-agent

./agent --config /path/to/agent.yml

server:
  # Leave blank to listen on all interfaces
  host:

  # Port to listen on
  port: 27973

  # Optional token for authenticating API requests
  token:

system:
  # When blank, the agent will attempt to infer the correct CPU temperature sensor, however
  # if it is unable to or it gets it wrong, you can override it using this option.
  # To list the available sensors, run `agent sensors:print`
  cpu-temp-sensor:

  # Whether to hide all mountpoints by default. Individual mountpoints
  # can then be shown using the `hide: false` option as seen below
  hide-mountpoints-by-default: false

  # List of mountpoints to show/hide in the API response, keyed by the mountpoint path
  # Optionally, also set a name to be displayed in the widget when hovering over the disk usage
  mountpoints:
    "/":
      hide: false
      name: Root

To log additional errors, use LOG_LEVEL=debug.

If you haven't specified a config file or it does not exist, the agent will instead use the below environment variables for configuration, useful when running in a container.

Sets server.token in the config file. Defaults to an empty string (no authentication).

Sets server.port in the config file. Defaults to 27973.

Sets system.cpu-temp-sensor in the config file. Defaults to an empty string (auto-detect).

Sets system.hide-mountpoints-by-default in the config file. Defaults to false.

Sets system.mountpoints in the config file. Accepts a comma-separated list of mountpoints, for example:

MOUNTPOINTS="/mnt/data, /mnt/backups"

If you set HIDE_MOUNTPOINTS_BY_DEFAULT=true then all mountpoints will be hidden by default, except for those specified in this variable.

volumes:
  - /dir/on/host:/dir/in/container:ro

To give a mountpoint a custom name, use the format <mountpoint>:<name>, for example:

MOUNTPOINTS="/mnt/data:Data, /mnt/backups:Backups"

To hide a mountpoint, use the prefix !, for example:

MOUNTPOINTS="/mnt/data:Data, !/etc/hostname"

Although the agent was primarily built to be used with Glance, you can still use its API to build your own monitoring solutions or custom widgets.

If a token is set in the configuration file, API requests must include an Authorization header with the value Bearer <token>.

Example response:

{
  "host_info_is_available": true,
  "boot_time": 1758747502,
  "hostname": "raspberrypi",
  "platform": "raspbian",
  "cpu": {
    "load_is_available": true,
    "load1_percent": 6,
    "load15_percent": 2,
    "temperature_is_available": true,
    "temperature_c": 41
  },
  "memory": {
    "memory_is_available": true,
    "total_mb": 3794,
    "used_mb": 115,
    "used_percent": 3,
    "swap_is_available": true,
    "swap_total_mb": 99,
    "swap_used_mb": 0,
    "swap_used_percent": 0
  },
  "mountpoints": [
    {
      "path": "/",
      "name": "",
      "total_mb": 29689,
      "used_mb": 12548,
      "used_percent": 44
    }
  ]
}

Returns 200 OK if the agent is running. This endpoint is used during the automatic installation to verify that the agent has started successfully.