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

# Agent configuration

> What the agent needs locally on the Patch server (an API key and a few log settings) and how everything else is configured in the Luumen UI.

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](/enterprise/connecting/defining-hosts), [Credentials](/enterprise/connecting/credentials), [Scheduling runs](/enterprise/installation/scheduling), and [Vault integration](/enterprise/installation/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:

```yaml theme={null}
luumen:
  api:
    key: "YOUR_API_KEY"
```

The full set of supported local options:

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

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

| 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`        |

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.

<Tip>
  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.
</Tip>

## 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:

| Setting                                                                                   | Documented at                                                   |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Host list (add one-by-one or bulk import)                                                 | [Defining hosts](/enterprise/connecting/defining-hosts)         |
| Per-host credentials and the default credential set                                       | [Credentials](/enterprise/connecting/credentials)               |
| Run schedule and cadence                                                                  | [Scheduling runs](/enterprise/installation/scheduling)          |
| HashiCorp Vault settings                                                                  | [Vault integration](/enterprise/installation/vault-integration) |
| Integration-specific settings (ServiceNow API key, observability provider, SAP BTP, etc.) | [Integrations](/enterprise/integrations/overview)               |

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](/enterprise/troubleshooting/common-issues) for common causes.