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

# Linux (.deb / .rpm)

> Install the Guardway agent on Linux fleets with the native .deb and .rpm packages through apt, dnf, Ansible, Puppet, Chef or Salt, and verify it starts for every user.

## What this is for

Linux ships as native packages: `guardway-agent_<version>-1_amd64.deb` and `_arm64.deb` for Debian
and Ubuntu, `guardway-agent-<version>-1.x86_64.rpm` and `.aarch64.rpm` for RHEL, Rocky, Alma and
Fedora. Installing the package is the whole install: it activates the agent for every signed-in
user right away and at each login after that, with no command to run.

Download from `https://api.guardway.ai/v1/downloads/gw-cli/latest/` or from the release page. Each
package has a `.sha256` next to it.

## Supported distributions

Any distribution with glibc 2.34 or newer and OpenSSL 3: Ubuntu 22.04 and later, Debian 12 and
later, RHEL, Rocky and Alma 9, and current Fedora. The tray icon needs a desktop (WebKitGTK 4.1,
GTK 3, AppIndicator); those libraries are recommended, not required, so a server or a
`--no-install-recommends` install gets the agent without a tray. RHEL 9 base repositories may lack
WebKitGTK 4.1, so the agent installs there without the tray.

## What the package installs

| Item | Path |
| - | - |
| Agent, engine and tray | `/usr/bin/gw-cli`, `/usr/bin/skillspector`, `/usr/bin/gw-tray` |
| Auto-start for every user (observe) | systemd user unit `ai.guardway.gw-cli.serve.service`, enabled globally |
| Managed service (managed mode) | `com.guardway.gw-cli.tap.service` and `.socket` |
| Agent updater | `guardway-gw-cli-updater.timer`, every 15 minutes |
| Per-user data | `~/.guardway` for each user |
| Machine-wide data (managed mode) | `/var/lib/guardway` |
| Install mode file | `/etc/guardway/install-mode` |
| Package log | `/var/log/guardway/package.log` |

## How to install

<Tabs>
  <Tab title="apt / dnf">
    ```sh theme={null}
    sudo apt install ./guardway-agent_<version>-1_amd64.deb        # Ubuntu, Debian
    sudo dnf install ./guardway-agent-<version>-1.x86_64.rpm       # RHEL, Rocky, Alma, Fedora
    ```

    To install the **managed** mode, write the mode file first:

    ```sh theme={null}
    echo managed | sudo tee /etc/guardway/install-mode
    sudo apt install ./guardway-agent_<version>-1_amd64.deb
    ```

    `observe` (the default), `managed` or `off` (install the files, activate nothing) are the accepted values. An upgrade keeps the machine's mode unless the file says otherwise.
  </Tab>

  <Tab title="Ansible">
    ```yaml theme={null}
    - name: Guardway agent
      hosts: developers
      become: true
      tasks:
        - name: Choose the install mode
          copy: { dest: /etc/guardway/install-mode, content: "observe\n", mode: "0644" }
        - name: Copy the package
          copy: { src: guardway-agent_{{ gw_version }}-1_amd64.deb, dest: /tmp/guardway-agent.deb }
        - name: Install
          apt: { deb: /tmp/guardway-agent.deb }
        - name: Check activation
          command: gw-cli hook --installed-mode
          register: gw_mode
          changed_when: false
          failed_when: gw_mode.stdout != "observe"
    ```

    Use the `dnf` module with the `.rpm` on Red Hat family hosts. Guard your task on `gw-cli hook --installed-mode`, which is the same answer the console reports.
  </Tab>

  <Tab title="Puppet, Chef, Salt">
    Manage the mode file, then the package resource (`package { 'guardway-agent': source => '/tmp/guardway-agent.deb', provider => dpkg }` and the `rpm` provider for Red Hat). Run enrollment as the target user, not as root. A plain script works the same way: write the mode file, run `apt install` or `dnf install`, check `gw-cli hook --installed-mode`.
  </Tab>
</Tabs>

<Note>
  A failed activation never fails the package, for example in a container without systemd. The files
  are installed, the reason is in `/var/log/guardway/package.log`, `gw-cli hook --installed-mode`
  answers `none`, and the next upgrade tries again.
</Note>

## After the install

The agent starts for every user who is signed in and for each user who signs in later; the install
prints who it started it for. On a machine where nobody has signed in since the install, nothing is
running yet, which is expected. Verify:

```sh theme={null}
gw-cli hook --installed-mode             # prints: observe | managed | none
gw-cli hook --status                     # what is registered and whether it is up
dpkg -s guardway-agent                   # or: rpm -q guardway-agent
```

Then [enroll the machine](/endpoint-ai-risk/connect/activate) as the signed-in user.

## Upgrading

Upgrades go through the package manager, so `dpkg` and `rpm` always know which version is
installed:

```sh theme={null}
sudo apt install ./guardway-agent_<new>-1_amd64.deb
sudo dnf upgrade ./guardway-agent-<new>-1.x86_64.rpm
```

With the update policy on **Auto-install**, the agent downloads the package for the selected
release, checks it against Guardway's signed release index and installs it the same way. If `apt`
or `dnf` is busy it tries again 15 minutes later. `gw-cli upgrade` by hand does not replace a
package-owned binary; it prints the `apt` or `dnf` command instead. See
[Agent updates](/endpoint-ai-risk/connect/updates).

Machines that were installed from the archive into `/usr/local/bin` move over by themselves: after
the package activates from `/usr/bin`, it removes Guardway's own copies from `/usr/local/bin`.

## Removing

```sh theme={null}
sudo apt remove guardway-agent      # keeps /var/lib/guardway and each user's ~/.guardway
sudo apt purge guardway-agent       # also deletes the machine-wide data
```

(`dnf remove guardway-agent` on the Red Hat family.) Removal stops the agent in every user's session
and returns any held skill before the files go. See [Uninstall & Recovery](/endpoint-ai-risk/agent/uninstall#other-platforms).

## Limits

* The packages are the supported path. The `.tar.gz` archive is for a per-user evaluation install in `~/.local/bin`; it has no machine-wide updater.
* Packages older than 0.2.160 cannot update themselves; install a current package over them once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.