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

# Architecture

> How the Luumen agent, your Patch server, your hosts, and the Luumen API and web app fit together.

Luumen Enterprise is structured around a single agent that runs inside your environment, a set of managed hosts the agent connects to over SSH or WinRM, and the Luumen API and web application that store data and present findings. This page describes each component and how data moves between them.

## Components

<CardGroup cols={2}>
  <Card title="Luumen agent" icon="microchip">
    A lightweight executable installed on your Patch server. Connects to each managed host on a schedule, collects system data, and pushes it to the Luumen API.
  </Card>

  <Card title="Patch server" icon="server">
    A single host inside your environment that runs the agent. Must have network access to every managed host and outbound HTTPS access to the Luumen API.
  </Card>

  <Card title="Monitored hosts" icon="hard-drive">
    The Linux and Windows hosts the agent connects to. Each host is added through the Luumen UI with its own credentials, or uses a default credential set you configure once.
  </Card>

  <Card title="Luumen API and web app" icon="cloud">
    Hosted by Apiphani (Apiphani-managed deployment) or inside your environment (self-hosted). Receives data from the agent, evaluates compliance checks, ingests vulnerability data from the NVD (and SAP Security Notes when SAP is in scope), and renders the UI.
  </Card>
</CardGroup>

## How data flows

<Steps>
  <Step title="Agent reads its configuration">
    On each scheduled run, the agent loads its local `config.yaml` (API endpoint, API key, optional Vault settings) and pulls its remote configuration from the Luumen API. The remote configuration includes the host list, default credentials, and schedule settings — see [Agent configuration](/enterprise/installation/agent-configuration).
  </Step>

  <Step title="Agent connects to each host">
    The agent opens an SSH session (Linux) or WinRM session (Windows) to each host in its list using the configured credentials. Connections originate from the Patch server.
  </Step>

  <Step title="Agent collects properties">
    For each host, the agent runs a fixed set of read commands and queries to collect OS data, hardware data, installed packages, and any application-specific properties configured for your workspace. See [What the agent collects](/enterprise/data/what-the-agent-collects).
  </Step>

  <Step title="Agent reports to the Luumen API">
    Collected properties are sent to the Luumen API over HTTPS using the API key in the local config. Each host's data is timestamped and persisted.
  </Step>

  <Step title="Luumen evaluates checks and alerts">
    The platform runs every compliance check assigned to each host group, matches hosts against the NVD (via OS and packages), and updates the dashboard. For SAP workspaces, SAP Security Note matching runs in parallel.
  </Step>
</Steps>

## Network direction

All traffic originates from inside your environment:

* **Patch server → hosts** — outbound SSH (port 22) or WinRM (port 5985/5986) to each managed host.
* **Patch server → Luumen API** — outbound HTTPS to the API base URL configured in `config.yaml`. No inbound connectivity to the Patch server is required from Luumen's infrastructure.

Luumen never initiates connections into your environment. Adding the agent does not require firewall changes on your managed hosts beyond the SSH or WinRM access your team already uses.

## Deployment topology

<Tabs>
  <Tab title="Apiphani-managed">
    * **Agent + Patch server:** inside your environment, managed by you.
    * **Luumen API + web app:** hosted by Apiphani.

    Most customers use this model. The agent posts to a Luumen-managed API endpoint (e.g., `https://ns2-api.apiphani.io/v2/api/v1`), and your team accesses the web app at a Luumen-managed URL.
  </Tab>

  <Tab title="Self-hosted">
    * **Agent + Patch server:** inside your environment.
    * **Luumen API + web app:** also inside your environment, in a cloud account or on-prem environment you control.

    Apiphani engineers handle the initial install of all components, including provisioning cloud resources and connecting the agent to your private API endpoint. Updates are coordinated with Apiphani.
  </Tab>
</Tabs>

## Where the agent fits in your operations

The agent is intentionally separate from the systems it monitors. It runs as a service on a single Patch server, queries hosts over the same protocols your team already uses for remote access, and writes nothing back to those hosts. This means:

* No additional agent installs on production hosts.
* No changes to firewall rules on the systems being monitored.
* No write access required from the agent's service user — the permissions it needs are read-only (with a small set of `sudo` exceptions documented in [Prerequisites](/enterprise/get-started/prerequisites)).

If the agent stops running, host data on the dashboard goes stale but no production system is affected.