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

# Install the agent

> Download the Luumen agent, place it on your Patch server, configure your API key, and register it as a system service.

The agent install is normally handled by an Apiphani engineer during [white-glove setup](/enterprise/installation/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:

```bash theme={null}
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):**

```bash theme={null}
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:**

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

Self-hosted deployments also override `base_url` to point at their own API endpoint. See [Agent configuration](/enterprise/installation/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:

```bash theme={null}
sudo ./agent-executable --install-service \
  --service-user <service-user> \
  --service-group <service-group>
```

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

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](/enterprise/installation/scheduling).

## 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](/enterprise/connecting/verifying-capture).

If no hosts appear at all, see [Troubleshooting](/enterprise/troubleshooting/common-issues#agent-fails-to-execute) — 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:

```bash theme={null}
./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.