[Yandex Cloud documentation](../../../../index.md) > [Yandex Monitoring](../../../index.md) > [Metric collection agent](index.md) > Installing and updating

# Installing and updating Yandex Unified Agent

{% note info %}

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

{% endnote %}

For more information, see [Prometheus metric collection agent](../../../operations/prometheus/ingestion/prometheus-agent.md).

## List of supported operating systems {#supported-os}

Unified Agent is supported by the following operating systems:

- Ubuntu 16.04 or higher (you can [install it using any method](#setup)).
- 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 {#before-you-begin}

Prior to installing Yandex Unified Agent, follow these steps:

1. Create a VM in Yandex Cloud or a host outside Yandex Cloud on one of the [supported operating systems](#supported-os), e.g., Ubuntu 16.04 or higher.

1. Optionally, [install Docker](https://docs.docker.com/install/) if you want to use Docker to run Unified Agent. Docker is pre-installed in Fedora CoreOS.
   - Set up a public IPv4 address (recommended).
   - [Configure Docker to work with IPv6](https://docs.docker.com/config/daemon/ipv6) and [enable network address translation](https://medium.com/@skleeschulte/how-to-enable-ipv6-for-docker-containers-on-ubuntu-18-04-c68394a219a2) if you cannot use a public IPv4 address.

1. [Create a service account](../../../../iam/operations/sa/create.md) in the folder you want to write metrics to and [assign it](../../../../iam/operations/sa/assign-role-for-sa.md) the `monitoring.editor` role.

1. Set up agent authorization in the Yandex Monitoring API:
   - If the agent is installed on a VM in Yandex Cloud, [link the service account you created](../../../../compute/operations/vm-connect/auth-inside-vm.md#link-sa-with-instance) to the VM. In that case, the agent will automatically receive the service account IAM token from the metadata service.
   - If the agent is installed on a host outside Yandex Cloud, [create an authorized key](../../../../iam/operations/authentication/manage-authorized-keys.md#create-authorized-key) for service accounts. For more information about delivering metrics from hosts outside Yandex Cloud, see [Delivering metrics from hosts outside Yandex Cloud](../../../operations/unified-agent/non-yc.md).


## Installation {#setup}

Install Unified Agent using one of the following methods:

{% list tabs group=unified_agent %}

- Docker image {#docker}

  Install Docker Engine. Use [this guide](https://docs.docker.com/engine/install/#supported-platforms) 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](../../../operations/unified-agent/linux_metrics.md) in Yandex Monitoring.

  To upload a Docker image, run this command:

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

- deb package {#deb}

  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:
  
      ```bash
      ubuntu_name="<full_OS_version_name>" \
      ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version)
  
      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 info %}
  
      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.
  
      {% endnote %}
  
      If you do not know the exact `ubuntu_name` value, display the list of available options for the latest Unified Agent version:
  
      ```bash
      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`:
  
      ```bash
      curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions
      ```
  
  1. Check the downloaded `deb` package version using the `ls` command.
  
      Result:
  
      ```bash
      yandex-unified-agent_<version>_amd64.deb
      ```
  
      Where `<version>` is the downloaded `deb` package version, e.g., `24.12.01`.
  
  1. To install the downloaded deb package, run this command:
  
      ```bash
      sudo dpkg -i yandex-unified-agent_<version>_amd64.deb
      ```
  
  1. To make sure Unified Agent is successfully installed and started, run this command:
     
     ```bash
     systemctl status unified-agent
     ```
     
     Result:
     
     ```bash
     ● 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](inputs.md#linux_metrics_input) and [agent health metrics](inputs.md#agent_metrics_input). You will be [charged](../../../pricing.md) for metric delivery.
  
      You can also [configure](configuration.md) the delivery of custom metrics or [logs to Cloud Logging](outputs.md#yc_logs_output).
  
  * 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.

- Binary file {#binary}

  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:

  ```bash
  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'
  ```

- When creating a VM {#vm}

  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](https://console.yandex.cloud), enable **Agent for delivering metrics** under **Monitoring**.

  To install the agent via the CLI, API, or Terraform, provide the following string in the [user metadata](../../../../compute/concepts/metadata/sending-metadata.md) (`user-data`):

  
  ```text
  #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](inputs.md#linux_metrics_input) and [agent health metrics](inputs.md#agent_metrics_input). You will be [charged](../../../pricing.md) for metric delivery.
  
      You can also [configure](configuration.md) the delivery of custom metrics or [logs to Cloud Logging](outputs.md#yc_logs_output).
  
  * 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 Yandex Monitoring.

  Update the agent manually via a binary file.

{% endlist %}


## Updating {#update}

Update Unified Agent using one of the following methods:

{% list tabs group=unified_agent %}

- Docker image {#docker}

  1. Stop the `ua` container:

      ```bash
      sudo docker stop ua
      ```

  1. Delete the container:

      ```bash
      sudo docker rm ua
      ```

  1. [Run](run-and-stop.md#run) the container.

- deb package {#deb}

  Re-download and [install](#setup) the latest deb package.

- Binary file {#binary}

  1. Delete the existing agent binary file.
  1. Download the latest version of the agent as a binary file:
  
      ```bash
      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'
      ```
  
  1. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for [delivering Linux system metrics](../../../operations/unified-agent/linux_metrics.md). For more information about the agent configuration, see [Configuration](configuration.md).
  
  
  1. Move the downloaded file to the `/bin/unified_agent` folder.
  1. [Restart](run-and-stop.md#run) the agent.
  
  To find out all available versions of the agent, run this command:
  
  ```(bash)
  curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions
  ```

- When creating a VM {#vm}

  1. Delete the existing agent binary file.
  1. Download the latest version of the agent as a binary file:
  
      ```bash
      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'
      ```
  
  1. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for [delivering Linux system metrics](../../../operations/unified-agent/linux_metrics.md). For more information about the agent configuration, see [Configuration](configuration.md).
  
  
  1. Move the downloaded file to the `/bin/unified_agent` folder.
  1. [Restart](run-and-stop.md#run) the agent.
  
  To find out all available versions of the agent, run this command:
  
  ```(bash)
  curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions
  ```

{% endlist %}


#### What's next {#what-is-next}

- [Learn how to run and stop Unified Agent](run-and-stop.md)
- [Read about Unified Agent concepts](index.md)
- [Learn more about configuring Unified Agent](configuration.md)
- [Read the Unified Agent operating guidelines](best-practices.md)