Skip to main content
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:
The full set of supported local options: That’s the whole file. Everything else has moved into the Luumen UI.

​
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. Environment variables take precedence over values in 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.

​
What’s configured in the UI

The bulk of what used to live in a long YAML file now lives in input fields in the Luumen UI. From the UI you control: Changes made in the UI apply on the next agent run. No file edits or service restarts are required.

​
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.