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

# 1.1.12 On prem agent

<img src="https://mintcdn.com/infimatrix/hdj8CnMy2GHELsJt/images/datasources/amazonECR.png?fit=max&auto=format&n=hdj8CnMy2GHELsJt&q=85&s=487d4cd3df9e60d0438efd3fdd99dc84" alt="Alt text" width="1918" height="868" data-path="images/datasources/amazonECR.png" />

## Overview

The **On-Prem Agent** allows you to scan applications, file systems, container images, and source code hosted within your local or private infrastructure.
The agent runs securely inside your environment and communicates with the **Zero-X Cloud** platform to send scan results.

This section is intended for:

**>** **End Users** (Security Analysts) <br />
**>** **DevOps / Platform Engineers**

***

## End-to-End On-Prem Agent Workflow

**1**. Create On-Prem Agent data source from UI<br />
**2**. Generate API Key and download agent bundle<br />
**3**. Install agent on local infrastructure<br />
**4**. Verify agent is online<br />
**5**. Trigger on-prem scans<br />
**6**. View findings across dashboards and reports<br />

***

## Step 1 – Add On-Prem Agent Data Source (End User)

### Navigation:

Connectors → Data Source → Add Data Source

### Steps:

**1**. Click **Add Data Source**.<br />
**2**. Select **On-Prem Agent**.<br />
**3**. Enter **Agent Name** (unique identifier for your host).<br />
**4**. Click **Create**.<br />

### System Actions:

**>** System creates a new on-prem agent entry.<br />
**>** System generates a **one-time API Key**.<br />
**>** **Important:** Copy and store the API Key securely. It will not be visible again.<br />
**>** System provides an **Agent Installer Bundle (.zip)** for download.

## Step 2 – On-Prem Agent Installation (DevOps / User)

### Zero-X Cloud On-Premise Agent Setup

The Zero-X agent is a lightweight background service that:

**>** Sends heartbeats to the Zero-X platform<br />
**>** Executes security scans locally<br />
**>** Securely uploads scan results<br />

***

### 2.1 Prerequisites

**>** Linux or macOS host (amd64)<br />
**>** <span style={{ color: "#86efac" }}>curl</span> and <span style={{ color: "#86efac" }}>unzip</span> installed<br />
**>** Network access to Zero-X Cloud platform URL<br />
**>** Required scanners installed and available in <code style={{ color: "#86efac" }}>\$PATH</code>
(e.g., <span style={{ color: "#86efac" }}>trivy, semgrep</span>)<br />

***

### 2.2 Installation Steps

#### 1. Download Agent Bundle

From the Zero-X Cloud UI, download:<br />

<code style={{ color: "#86efac" }}>zerox-agent-installer.zip</code>

#### 2. Unzip the Bundle

`unzip zerox-agent-installer.zip`

### 3. Run Installation Script

Execute the installation script with sudo privileges.

`sudo ./install-agent.sh <YOUR_API_KEY> <YOUR_ZEROX_PLATFORM_URL>`

#### Example:

`sudo ./install-agent.sh agent_abcdef1234567890 http://localhost:9002`

***

### 2.3 What the Installation Script Does

**>** Detects operating system (Linux / macOS)<br />
**>** Downloads the correct agent binary<br />
**>** Creates directories:<br />
   - <code style={{ color: "#86efac" }}>/opt/zerox-agent/</code> – agent binary<br />
   - <code style={{ color: "#86efac" }}>/etc/zerox-agent/</code> – configuration<br />
**>** Writes environment configuration file:<br />
   - <code style={{ color: "#86efac" }}>/etc/zerox-agent/.env</code><br />
**>** Configures background service:<br />
   - **Linux:** systemd service<br />
   - **macOS:** launchd service<br />
**>** Enables and starts the agent automatically<br />

***

## Step 3 – Verify Agent Status

### Linux (systemd)

`sudo systemctl status zerox-agent`<br />
`sudo journalctl -u zerox-agent -f`

### macOS (launchd)

`sudo launchctl list | grep cloud.zerox.agent`<br />
`log stream --predicate 'process == "zerox-agent"'`

### Expected Result

**>** Agent service is running<br />
**>** Heartbeats are sent successfully

***

## Step 4 – Agent Online Verification (UI)

### Navigation:

Connectors → Data Source

### Expected Behavior:

**>** On-Prem Agent status changes to Online<br />
**>** Host details become visible

***

## Step 5 – Trigger On-Prem Scan (End User)

### Navigation:

Connectors → New Scan

### Steps:

**1.** Click **New Scan**.<br />
**2.** Select **Target Type**: On-Premise Agent.<br />
**3.** Select **Scanner Type** as required:<br />
  - File System Scan<br />
  - Container Image Scan<br />
  - SAST Scan<br />
**4.** Select the **Agent / Resource**.<br />
**5.** Enter **Scan Target Path** (e.g., project directory path).<br />
**6.** Click **Scan Now**.

***

## Step 6 – View On-Prem Scan Findings

### Expected Behavior

After scan completion, findings are available across the platform:

**1. On-Prem Dashboard**<br />
**>** High-level severity summary:<br />
  - Critical<br />
  - High<br />
  - Medium<br />
  - Low<br />

**2. On-Prem Findings / Vulnerabilities Module**<br />
**>** Detailed vulnerability and security issues<br />
**>** CVE details, severity, impact, and remediation<br />

**3. Asset-Level View**<br />
**>** Findings mapped to:<br />
  - Servers<br />
  - Hosts<br />
  - IP Addresses<br />
  - Applications<br />

**4. can Results / Scan History**<br />
**>** Full scan execution details<br />
**>** Timestamp, scan status, and findings