Skip to main content
The agent install is normally handled by an Apiphani engineer during white-glove setup. This page documents the underlying steps so your team can audit the install, run the agent manually for ad-hoc tests, or re-install if the Patch server is rebuilt.

​
1. Download the binary

Agent binaries are distributed through Apiphani’s Agent Releases. Your Apiphani contact will share the download location and version targeted to your platform (Linux or Windows).

​
2. Place it on the Patch server

Copy the binary to a stable directory on the Patch server — typically something like /opt/luumen on Linux or C:\Program Files\Luumen on Windows. The agent doesn’t need much alongside it: just the optional config.yaml if you’re using one, and any SSH private keys you want to keep on the Patch server. On Linux, make the binary executable: 
chmod +x agent-executable

​
3. Configure the API key

The agent needs your Luumen API key to communicate with the API. You have two options: Option A — environment variable (recommended): 
export LUUMEN_API_KEY="YOUR_API_KEY"
In production, set this in the systemd unit (Environment= or EnvironmentFile=) so the agent’s service user picks it up automatically. Option B — config.yaml next to the binary: 
luumen:
  api:
    key: "YOUR_API_KEY"
Self-hosted deployments also override base_url to point at their own API endpoint. See Agent configuration for the full local-config reference. Everything else — host list, credentials, schedule, Vault, and integration settings — lives in the Luumen UI and is fetched by the agent on every run.

​
4. Install as a service

Register the agent as a system service so it starts automatically and runs on its schedule. Run this once during install: 
sudo ./agent-executable --install-service \
  --service-user <service-user> \
  --service-group <service-group>
The user that runs the install command needs sudo on the Patch server. The --service-user you pass is the user the agent runs as after install — that user only needs read access to the binary and config, plus whatever permissions are needed to connect to the monitored hosts.
Once installed as a service, the agent runs on the schedule configured in the Luumen UI (default: hourly). You can change the schedule any time without reinstalling — see Scheduling runs.

​
5. Verify the first run

After install, the agent triggers an initial run automatically. To confirm it succeeded:
  1. Open the Luumen UI and go to the Hosts page. You should see each host you’ve configured listed within a few minutes of the first run.
  2. Check the local log directory (default ./log, configurable via LUUMEN_LOG_DIR). The latest run produces a dated directory containing per-host check logs and an agent.log summary at the root.
If hosts appear but show a yellow warning icon, the agent reached them but had a credential or connection issue. See Verifying capture. If no hosts appear at all, see Troubleshooting — the most common causes are network access to the Luumen API or a missing/incorrect API key.

​
Running the agent manually

You don’t need to run the agent manually under normal operation — the service runs it on the configured schedule. For one-off testing (e.g., after adding new hosts, or to confirm a credential fix), invoke the binary directly without the --install-service flag: 
./agent-executable
The agent reads its API key from the environment or config.yaml, pulls the latest host list and settings from the Luumen API, runs a single collection cycle, and exits. Log output goes to the same log_dir as scheduled runs.

​
Reinstalling or upgrading

To upgrade to a new version of the agent:
  1. Stop the existing service.
  2. Replace the binary with the new version in the same location.
  3. Restart the service.
Configuration is preserved across upgrades — your API key and any UI-side settings carry over automatically. Your Apiphani contact will let you know if a specific upgrade requires a config change.

​
Uninstalling

To remove the agent, stop and uninstall the service using your platform’s service manager, then delete the binary and config directory. The host data already captured in Luumen is unaffected.