The agent’s configuration is split between two places:
- A small set of local settings on the Patch server — your API key and a few log preferences. These can live in a
config.yaml next to the agent binary or be passed as environment variables.
- Everything else — host list, credentials, schedule, Vault, integration settings — is configured through input fields in the Luumen UI. The agent fetches that configuration from the API on every run, so you can change it without redeploying anything on the Patch server.
This page covers the local side. UI-side configuration is documented under Defining hosts, Credentials, Scheduling runs, and Vault integration.
Local config
The local config is optional. If you set the same values via environment variables, you don’t need a file at all. When the file exists, it’s read from config.yaml in the same directory as the agent binary.
Minimum contents:
luumen:
api:
key: "YOUR_API_KEY"
| Property | Required | Type | Description |
|---|
luumen.api.key | Yes | string | Client API key used to authenticate every request from the agent. |
luumen.api.base_url | No | string | Base URL of the Luumen API. Defaults to Apiphani’s hosted endpoint. Self-hosted deployments override this with their own API URL. |
log_dir | No | string | Path to the directory where run logs are written. Defaults to ./log. |
log_retention_days | No | integer | Days of local logs to keep on the Patch server. Defaults to 30. |
service_name | No | string | Name of the registered system service. Defaults to luumen-agent. |
Environment variables
Each local option can also be set as an environment variable on the agent service. Useful when you’d rather not store the API key in a file at all, or you manage configuration through a secrets manager or systemd EnvironmentFile.
| Variable | Equivalent config key |
|---|
LUUMEN_API_KEY | luumen.api.key |
LUUMEN_API_BASE_URL | luumen.api.base_url |
LUUMEN_LOG_DIR | log_dir |
LUUMEN_LOG_RETENTION_DAYS | log_retention_days |
LUUMEN_SERVICE_NAME | service_name |
config.yaml. The agent reads them at startup, so if you change one you’ll need to restart the service.
For production, set LUUMEN_API_KEY via your systemd unit’s EnvironmentFile= directive on a root-only file. That keeps the API key out of config.yaml and out of process listings.
| Setting | Documented at |
|---|
| Host list (add one-by-one or bulk import) | Defining hosts |
| Per-host credentials and the default credential set | Credentials |
| Run schedule and cadence | Scheduling runs |
| HashiCorp Vault settings | Vault integration |
| Integration-specific settings (ServiceNow API key, observability provider, SAP BTP, etc.) | Integrations |
Validation
The agent validates its local config and its UI configuration on startup. If the API key is missing or wrong, or the API is unreachable, the agent writes the error to log_dir and exits without sending data. Check log/[date]/agent.log for the specific failure, and see Troubleshooting for common causes. 