# Starting AICM

## Install dependencies

The AICM files are at the following location:

/opt/qti-aic/tools/aic-manager
    Copy to clipboard

AICM requires several Python packages to run. Install the dependencies in a virtual environment as in the following example:

python -m venv <path-to-the-virtual-environment>
    source <path-to-the-virtual-environment>/bin/activate
    pip install -r requirements.txt
    Copy to clipboard

## Start the agent

After activating the virtual environment, start AICM using the following command:

usage: aicm_agent.py [-h] [-c CONFIG_FILE] [--ip IP] [--port PORT] [-u USERS] [--ssl-key SSL_KEY] [--ssl-cert SSL_CERT] [--qmonitor-ip QMONITOR_IP] [--qmonitor-port QMONITOR_PORT] [--log LOG]
                         [--max-log-size MAX_LOG_SIZE] [-v] [--dump-default-config DUMP_DEFAULT_CONFIG] [--dump-default-users DUMP_DEFAULT_USERS] [--collection KEY=VALUE [KEY=VALUE ...]]
    
    optional arguments:
      -h, --help            show this help message and exit
      -c CONFIG_FILE, --config_file CONFIG_FILE
                            Config file path
      --ip IP               IP address to bind to
      --port PORT           Port number to listen on
      -u USERS, --users USERS
                            Full path to users credentials file (.yaml)
      --ssl-key SSL_KEY, --ssl_key SSL_KEY
                            Path to the SSL key file. Required for HTTPS
      --ssl-cert SSL_CERT, --ssl_cert SSL_CERT
                            Path to the SSL certificate file. Required for HTTPS
      --qmonitor-ip QMONITOR_IP, --qmonitor_ip QMONITOR_IP
                            IP of QMonitor GRPC Server
      --qmonitor-port QMONITOR_PORT, --qmonitor_port QMONITOR_PORT
                            Port of QMonitor GRPC Server
      --log LOG             Path where to store logs
      --max-log-size MAX_LOG_SIZE, --max_log_size MAX_LOG_SIZE
                            Max sizes of logs in bytes
      -v, --verbose         Increase output verbosity
      --collection KEY=VALUE [KEY=VALUE ...]
                            Set a number of key-value pairs (do not put spaces before or after the = sign).
    
    Dump default files:
      Dumps the default files and then exit.
    
      --dump-default-config DUMP_DEFAULT_CONFIG, --dump_default_config DUMP_DEFAULT_CONFIG
                            Dump the default config to the specified folder and exit
      --dump-default-users DUMP_DEFAULT_USERS, --dump_default_users DUMP_DEFAULT_USERS
                            Dump the default users file to the specified folder and exit
    Copy to clipboard

You can also use a configuration file to provide the settings shown in the previous example. The
configuration file can be supplied using the `--config_file` option. If settings are found in both the command line arguments and in a configuration file, then the command line arguments take priority. The following is an example AICM configuration file.

# AICM Configuration
    
    # IP to bind AICM
    ip = 127.0.0.1
    
    # Port to bind AICM
    port = 9000
    
    # Full path to users credentials file
    # users =
    
    # SSL Key path
    # ssl_key =
    
    # SSL Certificate path
    # ssl_cert =
    
    # IP of QMonitor GRPC Server
    qmonitor_ip = localhost
    
    # Port of QMonitor GRPC Server
    qmonitor_port = 62472
    
    # Path to directory where to store logs
    # log =
    
    # Max sizes of logs in bytes
    max_log_size = 100000000
    
    # Verbosity of AICM agent
    verbose = 0
    
    # KEY=VALUE for defining collection intervals in milliseconds for each collection
    collection = [HEALTH=1000, DDR_BW=1000, PCI=1000, RAS_ECC_ERROR=10000]
    Copy to clipboard

You can also run AICM in a service-like manner :

sudo bash scripts/start_aicm_agent.sh
    Copy to clipboard

Once running, test the APIs at `<ip>:<port>/docs` using the
SwaggerUI.

## Stop the agent

There are two ways to stop AICM based on how it was started:

- If you used `python aicm_agent.py` to start it, press `Ctrl+C` to stop it.
- If you used `scripts/start_aicm_agent.sh` to start it, use the following command to stop it.

> 
> 
> sudo bash scripts/stop_aicm_agent.sh
>         Copy to clipboard

## Setup basic access authentication

Because [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) is
used as the authentication method, you must authenticate all
requests to the API. The accepted credentials are stored in the `.users.yaml` file. You can add/modify the credentials using the following syntax:

credentials:
      - username: admin
        hash: $2b$12$rEQTKF4IVHKPyeX6miseJ.xOjhmI5OFqlLuwE2OB4CuEIvHC2IFP6
        note: "Example of credential"
    Copy to clipboard

The credentials must be in every request made to the HTTP Rest
Endpoints. `bcrypt` hashes the password for security purposes. You can use the script at
`/scripts/hash_password.py` to get the hash.  Replace `<password>` and run the following command to get the hash.

python ./scripts/hash_password.py <password>
    Copy to clipboard

## HTTPS

Basic authentication is a simple mechanism for authentication. For added
security, use HTTPS which requires that you provide
a certificate and key upon startup. The following example shows the arguments for passing the key and certificate.

--ssl-key SSL_KEY    Path to the SSL key file. Needs to be provided for
                         HTTPS
    --ssl-cert SSL_CERT  Path to the SSL certificate file. Needs to be provided
                         for HTTPS
    Copy to clipboard

## Metrics

The metrics served by AICM are shown below (stored in
`docs/metrics.csv`).  In addition to a set of core metrics, AICM
provides reliability, availability, and serviceability (RAS) error statuses.

| Model | Field Name | Description |
| --- | --- | --- |
| Model | Field Name | Description |
| HealthDataModel | dev\_status | Status of the device |
| HealthDataModel | mhi\_id | MHI ID |
| HealthDataModel | pci\_address | PCI Address of the device |
| HealthDataModel | pci\_info | PCI Info |
| HealthDataModel | max\_link\_speed | Max Link Speed |
| HealthDataModel | max\_link\_width | Max Link Width |
| HealthDataModel | current\_link\_speed | Current Link Speed |
| HealthDataModel | current\_link\_width | Current Link Width |
| HealthDataModel | dev\_link | Dev Link Name |
| HealthDataModel | hw\_version | Hardware version |
| HealthDataModel | hw\_serial\_string | HW Serial Number |
| HealthDataModel | fw\_version | Firmware version |
| HealthDataModel | fw\_qc\_image\_version | Qualcomm firmware identification string |
| HealthDataModel | fw\_oem\_image\_version | OEM custom firmware identification string |
| HealthDataModel | fw\_image\_variant | Firmware image variant, e.g. debug, release, etc |
| HealthDataModel | device\_capabilities | Device Firmware Features |
| HealthDataModel | current\_boot\_interface | Boot Interface |
| HealthDataModel | nsp\_version | NSP version |
| HealthDataModel | nsp\_qc\_image\_version | NSP Image string |
| HealthDataModel | nsp\_oem\_image\_version | Image string provided by OEM |
| HealthDataModel | nsp\_image\_variant | NSP image variant, e.g. debug, release |
| HealthDataModel | dram\_total\_kb | Total RAM in system in KB |
| HealthDataModel | dram\_free\_kb | Amount of RAM free in KB |
| HealthDataModel | dram\_fragmentation\_percentage | Percentage of DRAM fragmentation |
| HealthDataModel | vc\_total | Total number of virtual channels on the system |
| HealthDataModel | vc\_free | Number of available virtual channels |
| HealthDataModel | pc\_total | Total number of Physical Channels |
| HealthDataModel | pc\_reserved | Number of reserved Physical Channels |
| HealthDataModel | nsp\_total | Number of neural processors on the system |
| HealthDataModel | nsp\_free | Number of available neural processors |
| HealthDataModel | dram\_bw\_KBps | DRAM bandwidth in Kbytes/second, averaged over last ~100 ms |
| HealthDataModel | mcid\_total | Total number of multicast IDs available on the system |
| HealthDataModel | mcid\_free | Number of available multicast IDs |
| HealthDataModel | semaphore\_total | Total number of semaphores available on the system |
| HealthDataModel | semaphore\_free | Number of available semaphores |
| HealthDataModel | num\_constant\_loaded | Number of constants loaded, each load of constants increments by 1 |
| HealthDataModel | num\_constant\_in\_use | Number of loaded constants that are actively used by networks running on the system |
| HealthDataModel | num\_networks\_loaded | Number of neural networks loaded in memory on the system |
| HealthDataModel | num\_networks\_active | Number of neural networks currently actively computing on the system |
| HealthDataModel | neural\_processor\_frequency\_Mhz | Nominal operating frequency of the neural processors, all processors are having the same max clock |
| HealthDataModel | ddr\_frequency\_Mhz | Nominal operating frequency of DDR memory |
| HealthDataModel | compute\_noc\_frequency\_Mhz | Nominal operating frequency of compute network on chip |
| HealthDataModel | memory\_noc\_frequency\_Mhz | Nominal operating frequency of memory network on chip |
| HealthDataModel | system\_noc\_frequency\_Mhz | Nominal operating frequency of system network on chip |
| HealthDataModel | metadata\_version | Metadata version |
| HealthDataModel | nnc\_protocol\_version | NNC protocol version |
| HealthDataModel | sbl\_image | SBL image string |
| HealthDataModel | pvs\_image\_version | PVS image version |
| HealthDataModel | nsp\_defective\_pg\_mask | Defective NSP mask |
| HealthDataModel | num\_retired\_ddr\_pages | Number of retired ddr pages |
| HealthDataModel | need\_reset\_to\_retire\_pages | Reset required to retire pending pages |
| HealthDataModel | board\_serial | Board serial |
| HealthDataModel | soc\_temparature\_degree\_C | SOC temperature in Degree Celsius |
| HealthDataModel | board\_power\_watts | Board power in Watts |
| HealthDataModel | tdp\_cap\_watts | Thermal Design Power cap in Watts |
| HealthDataModel | sku\_type | SKU Type |
| HealthDataModel | complex\_id | Complex ID |
| HealthDataModel | soc\_power\_watts | SOC Power in Watts |
| HealthDataModel | soc\_tdp\_cap\_watts | SOC Thermal Design Power cap in Watts |
| PciDataModel | byte\_count\_rx | Bytes received on PCIE |
| PciDataModel | byte\_count\_tx | Bytes sent on PCIE |
| DdrBwDataModel | byte\_count\_total | Sum of the NSP individual byte count |
| DdrBwDataModel\_NspDdrBwDataModel | byte\_count | DDR Byte Count for this NSP |
| RasErrorsDataModel | ras\_ddr\_correctable\_error\_count | Count of Correctable Errors received from ras\_ddr |
| RasErrorsDataModel | ras\_ddr\_uncorrectable\_error\_count | Count of Uncorrectable Errors received from ras\_ddr |
| RasErrorsDataModel | ras\_mcw\_correctable\_error\_count | Count of Correctable Errors received from ras\_mcw |
| RasErrorsDataModel | ras\_mcw\_uncorrectable\_error\_count | Count of Uncorrectable Errors received from ras\_mcw |
| RasErrorsDataModel | ras\_imem\_correctable\_error\_count | Count of Correctable Errors received from ras\_imem |
| RasErrorsDataModel | ras\_imem\_uncorrectable\_error\_count | Count of Uncorrectable Errors received from ras\_imem |
| RasErrorsDataModel | ras\_nsp\_correctable\_error\_count | Count of Correctable Errors received from ras\_nsp |
| RasErrorsDataModel | ras\_nsp\_uncorrectable\_error\_count | Count of Uncorrectable Errors received from ras\_nsp |

Last Published: May 01, 2026

[Previous Topic
AIC-manager](https://docs.qualcomm.com/bundle/publicresource/80-99100-3/topics/index_aic-manager.md) [Next Topic
Feature overview](https://docs.qualcomm.com/bundle/publicresource/80-99100-3/topics/index_feature-overview.md)