Skip to main content
Before an Apiphani engineer installs the agent, your team needs to provide a Patch server, confirm network access, and prepare a service user with the right permissions on each managed host. This page lists every prerequisite.

​
Patch server

The Patch server is the host that runs the Luumen agent. You need exactly one per Luumen client.
RequirementDetails
Operating systemLinux (any modern distribution with systemd) or Windows Server
CPU and memoryModest — the agent is lightweight. 2 vCPU / 4 GB RAM is sufficient for hundreds of hosts.
DiskA few GB for the binary and rolling logs (log_retention_days defaults to 30)
NetworkOutbound HTTPS to the Luumen API. Outbound SSH or WinRM to every managed host.
AccessA service user with permission to execute the agent binary and read its config and key files.
The Patch server should be a stable host that is not regularly rebuilt or rotated. The agent runs as a system service, so the server needs to stay up to keep the dashboard current.

​
Network access

The Patch server must be able to reach:
  • The Luumen API base URL configured in config.yaml (HTTPS, default port 443).
  • Every managed host over SSH (port 22) or WinRM (port 5985 for HTTP, 5986 for HTTPS).
You can verify outbound API access from the Patch server with a quick curl: 
curl -H "api-key: YOUR_API_KEY_HERE" "https://ns2-api.apiphani.io/v2/api/v1/config"
A successful response confirms network access and a valid API key. See Troubleshooting if the request hangs or returns an error.

​
Service user permissions

The agent runs as a dedicated service user on the Patch server, and authenticates to each managed host as a user you control on that host. The required permissions vary by platform.
The permissions below cover the agent’s current data collection. As new properties are added, the required permissions can change. We’ll document changes here and notify customers ahead of upgrades that require new permissions.

​
Linux

The service user on each Linux host needs sudo access to the following commands for standard OS data collection:
CommandWhy the agent needs it
dmidecodeReads DMI tables for hardware detection (vendor, model, serials)
getenforceQueries SELinux status
tuned-admQueries the tuned daemon for active performance profile
/var/spool/cron/tabs/rootReads root’s crontab for scheduled-job inventory
Application-specific properties may require additional read permissions on the relevant directories. If you’ve enabled the SAP integration, for example, the service user needs broad read access to SAP files under the SAP user’s directories — the exact paths are determined during white-glove setup. See SAP integration.

​
Windows

On Windows hosts, the service user needs the following access types:
AccessWhy the agent needs it
Registry accessReads application data and installed software metadata
WMI queriesRuns Get-CimInstance and Get-WmiObject to collect OS, memory, CPU, and swap information
Process and service infoRuns Get-Process and Get-Service for service inventory

​
Patch server service user

The user that runs the agent binary on the Patch server itself also needs:
  • Execute permission on the agent binary (chmod +x on Linux).
  • Read permission on config.yaml and any SSH private keys referenced in the host list.
  • sudo access on the Patch server when installing the agent as a service (during the install command only).
  • If using HashiCorp Vault: a way to provide the Vault token, typically the VAULT_TOKEN environment variable.

​
What Apiphani handles

The white-glove install covers everything beyond providing the Patch server and the service user:
  • Downloading and placing the agent binary.
  • Writing the initial config.yaml.
  • Installing the agent as a service and verifying the first scheduled run.
  • Configuring the remote agent config (host list, default credentials) in the Luumen UI.
  • For self-hosted deployments, provisioning the Luumen API and web app.
See White-glove setup for what Apiphani needs from your team to get started.