> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HiveOS Installation

> Install and run a Quai Network GPU miner on HiveOS.

## Introduction

Here, we'll be installing [quai-gpu-miner](https://github.com/dominant-strategies/quai-gpu-miner), the implementation of a Quai Network ProgPOW miner. This tutorial focuses on installing and running quai-gpu-miner on [HiveOS](https://hiveon.com/os/), a Linux based operating system that makes GPU mining easy. HiveOS also provides a web based dashboard for streamlined management and maintenance of your Quai Network GPU miner.

### Requirements

In order to run the quai-gpu-miner on HiveOS and mine valid blocks, you'll need the following:

<CardGroup cols={3}>
  <Card title="Synced go-quai node" href="/guides/client/node" icon="computer" />

  <Card title="Configured Stratum proxy" href="/guides/client/stratum" icon="router" />

  <Card title="HiveOS machine" icon="hive" />

  <Card title="AMD or NVIDIA GPU" icon="microchip" />

  <Card title="4GB+ of RAM" icon="usb-drive" />
</CardGroup>

## Environment Setup

### HiveOS

For this tutorial, you'll need a HiveOS machine. Instructions for how to install HiveOS on your rig and configure it can be found on the [HiveOS installation documentation](https://hiveon.com/install/).

### Drivers and Updates

Once you've installed and set up HiveOS on your rig, you'll need to update drivers, install some GPU utility packages, and ensure Hive is up to date.

<Tabs>
  <Tab title="CUDA Drivers">
    Prior to starting updates and installs, we need to switch users. Do this by running:

    ```bash theme={null}
    sudo su user
    ```

    To upgrade HiveOS, run:

    ```bash theme={null}
    sudo selfupgrade
    ```

    To update and install necessary graphics card drivers, run:

    ```bash theme={null}
    sudo nvidia-driver-update
    ```
  </Tab>

  <Tab title="OpenCL Drivers">
    Prior to starting updates and installs, we need to switch users. Do this by running:

    ```bash theme={null}
    sudo su user
    ```

    To upgrade HiveOS, run:

    ```bash theme={null}
    sudo selfupgrade
    ```

    To update and install necessary graphics card drivers, run:

    ```bash theme={null}
    sudo nvidia-driver-update
    ```

    Once drivers have been installed and updated, we'll need to install OpenCL:

    ```bash theme={null}
    sudo amd-ocl-install 22.20
    ```
  </Tab>
</Tabs>

## Installation

Now that all of our dependencies are installed, we can install quai-gpu-miner. There are two options for installation:

<Tabs>
  <Tab title="Pre-compiled Binaries">
    <Tip>
      Installing the GPU miner via pre-compiled binaries is recommended for vast majority of users. It is the simplest and fastest way to get started mining.
    </Tip>

    The latest release of quai-gpu-miner is available for download from the [GPU miner releases page](https://github.com/dominant-strategies/quai-gpu-miner/releases).

    To download the binaries for the latest release into the `output` directory, run the following command:

    <Tabs>
      <Tab title="NVIDIA Cards">
        ```bash theme={null}
        sudo wget -P output https://github.com/dominant-strategies/quai-gpu-miner/releases/latest/download/quai-gpu-miner-nvidia
        ```
      </Tab>

      <Tab title="AMD Cards">
        ```bash theme={null}
        sudo wget -P output https://github.com/dominant-strategies/quai-gpu-miner/releases/download/v0.4.0/quai-gpu-miner-amd
        ```
      </Tab>
    </Tabs>

    This will create an `output` directory with two built binaries in it: `quai-gpu-miner-amd` and `quai-gpu-miner-nvidia`. For the card type you have, run the following command to make the binary executable:

    <Tabs>
      <Tab title="NVIDIA Cards">
        ```bash theme={null}
        chmod +x output/quai-gpu-miner-nvidia
        ```
      </Tab>

      <Tab title="AMD Cards">
        ```bash theme={null}
        chmod +x output/quai-gpu-miner-amd
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Compile from Source">
    <Warning>
      Compiling from source may take a while to complete, and will require about 10gb of RAM. If your machine does not have the required RAM, it is recommend to install via pre-compiled binaries.
    </Warning>

    The [quai-gpu-miner](https://github.com/dominant-strategies/quai-gpu-miner) repository contains a [automated script](https://github.com/dominant-strategies/quai-gpu-miner/blob/main/deploy_miner.sh) that can be used to compile and configure the miner. The `deploy_miner.sh` script will install the following build dependencies and build the latest version of the miner:

    * git
    * cmake
    * build-essential
    * mesa-common-dev
    * [Nvidia CUDA Toolkit v12.6](https://developer.nvidia.com/cuda-12-6-0-download-archive)

    To download the script, run the following command:

    ```bash theme={null}
    wget https://raw.githubusercontent.com/dominant-strategies/quai-gpu-miner/refs/heads/main/deploy_miner.sh
    ```

    Make the `deploy_miner.sh` script executable:

    ```bash theme={null}
    sudo chmod +x deploy_miner.sh
    ```

    To compile and configure the miner, run the script with the following command:

    ```bash theme={null}
    sudo ./deploy_miner.sh
    ```

    This will create an `output` directory with two built binaries in it: `quai-gpu-miner-amd` and `quai-gpu-miner-nvidia`. For the card type you have, run the following command to make the binary executable:

    <Tabs>
      <Tab title="NVIDIA">
        ```bash theme={null}
        chmod +x output/quai-gpu-miner-nvidia
        ```
      </Tab>

      <Tab title="AMD">
        ```bash theme={null}
        chmod +x output/quai-gpu-miner-amd
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Configure and Run

### Run

To run the miner, you'll need a Stratum proxy to connect to. Visit the [quai-stratum-proxy](/guides/client/stratum) docs for information on how to install and configure it. The proxy configuration will determine which shard your gpu-miner is running on and the address payouts are awarded to.

First, you'll need to obtain the IP Address and port your proxy is running on from the Stratum proxy logs. The default port is `3333`.

<Note>
  If your miner and proxy are on the same machine, the `PROXYIPADDRESS` will be `localhost`. If your miner and proxy are not on the same
  machine, you may need to port forward the proxy port.
</Note>

Once you've obtained the IP Address and port, run the miner with the following command, making sure to replace `PROXYIPADDRESS` with the IP Address and `STRATUMPORT` with the port your proxy is running on:

<Tabs>
  <Tab title="NVIDIA">
    ```bash theme={null}
    ./output/quai-gpu-miner-nvidia -U -P stratum://PROXYIPADDRESS:STRATUMPORT
    ```
  </Tab>

  <Tab title="AMD">
    ```bash theme={null}
    ./output/quai-gpu-miner-amd -G -P stratum://PROXYIPADDRESS:STRATUMPORT
    ```
  </Tab>
</Tabs>

The quai-gpu-miner should now be running and outputting logs to the terminal.

<Warning>
  Do not start the miner before confirming your node has fully synced. Mining while your node is not synced will result in the mining of
  **invalid blocks** and **wasted hash**.
</Warning>

### Stop

To stop the miner, simply use **CTRL+C** to kill the terminal process. Once logs are no longer being outputted to the terminal, the miner has stopped.