Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Installing and updating Yandex Unified Agent

Written by
Updated at June 4, 2026

Note

As of version 25.03.80, Unified Agent can collect and transmit Prometheus metrics.

For more information, see Prometheus metric collection agent.

List of supported operating systems

Unified Agent is supported by the following operating systems:

  • Ubuntu 16.04 or higher (you can install it using any method).
  • Debian 9 or higher (Docker image, deb package, or binary file).
  • CentOS 7 or higher (Docker image).
  • Fedora 32 or higher (Docker image).
  • Fedora CoreOS (Docker image).

Before you begin installation

Prior to installing Yandex Unified Agent, follow these steps:

  1. Create a VM in Yandex Cloud or a host outside of Yandex Cloud on one of the supported operating systems, e.g., Ubuntu 16.04 or higher.

  2. Optionally, install Docker if you want to use Docker to run Unified Agent. Docker is pre-installed in Fedora CoreOS.

  3. Create a service account in the folder you want to write metrics to and assign it the monitoring.editor role.

  4. Set up agent authorization in the Monium API:

Installation

Install Unified Agent using one of the following methods:

Install Docker Engine. Use this guide to install and run Docker for your operating system.

Unified Agent is distributed as a Docker image. The image is published in the cr.yandex/yc repository with the unified_agent name and the latest tag. The image includes a binary file with the agent and a configuration file used to set up the agent for Linux system metric delivery in Monium.

To upload a Docker image, run this command:

sudo docker pull cr.yandex/yc/unified-agent:latest

Unified Agent is distributed as a deb package for Ubuntu 16.04 or higher and Debian 9 or higher. The package contains a binary file with the agent and a configuration file located at /etc/yandex/unified_agent/config.yml.

To install Unified Agent:

  1. Download the latest deb package version:

    ubuntu_name="<full_OS_version_name>" \
ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb'

    Where ubuntu_name is the operating system version in ubuntu-<version_number>-<code_name> format. Specify the value exactly as it is used in the package folder name:

    • ubuntu-16.04-xenial
    • ubuntu-18.04-bionic
    • ubuntu-20.04-focal
    • ubuntu-22.04-jammy (starting with 23.03.02)
    • ubuntu-24.04-noble

    Note

    When installing Unified Agent on Debian 9, only deb packages for ubuntu-16.04-xenial and lower are supported; on Debian 10, only packages for ubuntu-18.04-bionic and lower are supported.

    If you do not know the exact ubuntu_name value, display the list of available options for the latest Unified Agent version:

    ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version)
aws s3 ls s3://yc-unified-agent/releases/${ua_version}/deb/ \
  --endpoint-url https://storage.yandexcloud.net \
  --no-sign-request | awk '{print $2}' | tr -d '/'

    You can also download a specific Unified Agent version. Do it by looking up the available versions and specifying the one you need instead of latest-version:

    curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

  2. Check the downloaded deb package version using the ls command.

    Result:

    yandex-unified-agent_<version>_amd64.deb

    Where <version> is the downloaded deb package version, e.g., 24.12.01.

  3. To install the downloaded deb package, run this command:

    sudo dpkg -i yandex-unified-agent_<version>_amd64.deb

  4. To make sure Unified Agent is successfully installed and started, run this command:

    systemctl status unified-agent

    Result:

    ● unified-agent.service - Yandex Unified Agent service
     Loaded: loaded (/lib/systemd/system/unified-agent.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2025-10-01 08:49:44 UTC; 27min ago
   Main PID: 1106 (unified_agent)
      Tasks: 8 (limit: 2308)
     Memory: 5.2M
        CPU: 136ms
     CGroup: /system.slice/unified-agent.service
             └─1106 /usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml --log-priority NOTICE

The Unified Agent installation involves the following steps:

  • Installing the unified_agent executable.

  • Installing the main configuration file. The configuration file is set up to send basic VM metrics and agent health metrics. You will be charged for metric delivery.

    You can also configure the delivery of custom metrics or logs to Monium.Logs.

  • Configuring the initialization system and adding the new unified-agent service. This service runs at system startup.

  • Creating the unified_agent user with uid 1515 and a group with the same name and gid 1515.

    If these uid and gid are not available (already in use), the user and group are created without explicitly specifying any uid and gid.

  • Creating and configuring access to the /etc/yandex/unified_agent/conf.d custom configuration directory.

  • Creating and configuring access to the /var/lib/yandex/unified_agent custom storage directory.

Unified Agent is distributed as a binary file built for the x86-64/amd64 architecture for Ubuntu 16.04 or higher.

To download the latest version of the agent's binary file, run:

ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

You can install Unified Agent when creating a VM through the management console, CLI, API, or Terraform.

To install the agent from the management console, enable Monitoring under Agent for delivering metrics.

To install the agent via the CLI, API, or Terraform, provide the following string in the user metadata (user-data):

#cloud-config\nruncmd:\n  - wget -O - https://monitoring.api.cloud.yandex.net/monitoring/v2/unifiedAgent/config/install.sh | bash

To install the agent and send metrics, make sure the VM has access to the internet.

The Unified Agent installation involves the following steps:

  • Installing the unified_agent executable.

  • Installing the main configuration file. The configuration file is set up to send basic VM metrics and agent health metrics. You will be charged for metric delivery.

    You can also configure the delivery of custom metrics or logs to Monium.Logs.

  • Configuring the initialization system and adding the new unified-agent service. This service runs at system startup.

  • Creating the unified_agent user with uid 1515 and a group with the same name and gid 1515.

    If these uid and gid are not available (already in use), the user and group are created without explicitly specifying any uid and gid.

  • Creating and configuring access to the /etc/yandex/unified_agent/conf.d custom configuration directory.

  • Creating and configuring access to the /var/lib/yandex/unified_agent custom storage directory.

Once the VM is deployed, Unified Agent will be started automatically and begin delivering basic VM metrics to Monium.

Update the agent manually via a binary file.

Updating

Update Unified Agent using one of the following methods:

  1. Stop the ua container:

    sudo docker stop ua

  2. Delete the container:

    sudo docker rm ua

  3. Run the container.

Re-download and install the latest deb package.

  1. Delete the existing agent binary file.

  2. Download the latest version of the agent as a binary file:

    ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

  3. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for delivering Linux system metrics. For more information on agent configuration, see Configuration.

  4. Move the downloaded file to the /bin/unified_agent folder.

  5. Restart the agent.

To find out all available versions of the agent, run this command:

curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

  1. Delete the existing agent binary file.

  2. Download the latest version of the agent as a binary file:

    ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

  3. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for delivering Linux system metrics. For more information on agent configuration, see Configuration.

  4. Move the downloaded file to the /bin/unified_agent folder.

  5. Restart the agent.

To find out all available versions of the agent, run this command:

curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

Installation and configuration example

This example shows how to install Unified Agent from a deb package and configure it to collect metrics.

To set up Unified Agent on a virtual machine, follow these steps:

  1. Create a service account in the folder you want to write metrics to and assign it the monitoring.editor role.

  2. Create your VM. Under Additional, select the service account you created in the previous step.

  3. Connect to the VM over SSH.

  4. Install Unified Agent:

    1. Get superuser privileges:

      sudo -i

    2. Download the deb package with the latest version of Unified Agent for your OS (e.g., ubuntu-22.04-jammy):

      ubuntu_name="ubuntu-22.04-jammy"
ua_version=$(curl -s https://storage.yandexcloud.net/yc-unified-agent/latest-version) bash -c 'curl -s -O https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb'

      The command will find the latest version of Unified Agent and download its deb package to your VM.

    3. Install the Unified Agent version from the package (e.g., 24.07.02):

      dpkg -i yandex-unified-agent_24.07.02_amd64.deb

    4. Check the Unified Agent status:

      systemctl status unified-agent.service
      Result
      unified-agent.service - Yandex Unified Agent service
   Loaded: loaded (/usr/lib/systemd/system/unified-agent.service; enabled; preset: enabled)
   Active: active (running) since Mon 2024-08-19 17:32:24 UTC; 1min 49s ago
 Main PID: 7106 (unified_agent)
    Tasks: 7 (limit: 2275)
   Memory: 3.6M (peak: 3.9M)
      CPU: 19ms
   CGroup: /system.slice/unified-agent.service
           └─7106 /usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml --log-priority NOTICE
            CGroup: /system.slice/unified-agent.service

Aug 19 17:32:24 ua-test-vm systemd[1]: Started unified-agent.service - Yandex Unified Agent service.
Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.815279Z 7106 15778840110569512124 NOTICE agent starting, revision [14433827]
Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.815307Z 7106  15778840110569512124 NOTICE agent monitoring service [:16300]
Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.815632Z 7106 15778840110569512124 NOTICE agent status service [localhost:16301]
Aug 19 17:32:24 ua-test-vm unified_agent[7106]: 2024-08-19T17:32:24.816002Z 7106  15778840110569512124 NOTICE agent started

  5. Configure Unified Agent:

    1. Open the Unified Agent configuration file:

      vim /etc/yandex/unified_agent/config.yml

    2. Add the metrics collection settings to the configuration file. The final file should look like this:

      monitoring:
  port: 16300

status:
  port: 16301

channels:
  - name: yc_metrics_channel
    channel:
      output:
        plugin: yc_metrics
        config:
          folder_id: "a1bs81qpemb4********"
          iam:
            cloud_meta: {}

routes:
  - input:
      id: linux_metrics_input
      plugin: linux_metrics
      config:
        poll_period: 60s
    channel:
      channel_ref:
        name: yc_metrics_channel

import:
  - /etc/yandex/unified_agent/conf.d/*.yml

    3. Restart Unified Agent:

      systemctl restart unified-agent.service

    4. Check the Unified Agent status:

      systemctl status unified-agent.service

Check the collected metrics:

  1. In the management console, select the folder where metrics are collected.
  2. Go to Monium.
  3. In the left-hand panel, select  Metrics.
  4. In the query editor, in the line with the cloud and folder names, specify the following:
    • service = custom
    • cluster = default
    • name = memory.Active
    • host = <VM_name>.
  5. Click Execute query.
    The chart that appears will display metrics collected by Unified Agent.

What's next

Previous
Overview
Next
Starting and stopping