---
id: agent-config
title: Agent configuration
sidebar_label: Agent config
---

The agent reads no environment variables. Everything is in one YAML file.

## Location

| Platform | Path                                |
| -------- | ----------------------------------- |
| Linux    | `/etc/vantage/config.yaml`          |
| Windows  | `%ProgramData%\vantage\config.yaml` |

Directory `0700`, file `0600`. The install script sets both.

## Contents

```yaml
server_url: "vantage.yourdomain.com:9090"
server_id: "<uuid>"
pre_reg_token: "<token>" # removed after the first successful Register()
agent_token: "" # written by the agent after Register()
poll_interval: 30s
tls: true
```

| Field           | Meaning                                                               |
| --------------- | --------------------------------------------------------------------- |
| `server_url`    | `host:port` of the gRPC endpoint. Comes from the server's `GRPC_HOST` |
| `server_id`     | The identity issued when the enrolment was created                    |
| `pre_reg_token` | Single-use, one hour. Cleared once registration succeeds              |
| `agent_token`   | The permanent credential, written by the agent itself                 |
| `poll_interval` | How often the agent polls for key state. Default `30s`                |
| `tls`           | Whether to use TLS. Leave `true`                                      |

:::danger This file is the credential
`agent_token` is plaintext here and nowhere else the control plane holds only
its SHA-256. Anyone who can read this file can act as this agent. That is why
it is `0600` and the directory is `0700`.
:::

## Startup sequence

```
1. Load the config
2. pre_reg_token present → register → save agent_token,
   clear pre_reg_token, reconnect
3. Start: command stream · hourly update check · inventory · monitors
4. Enter the key poll loop
```

## The poll loop

```
1. Ask the control plane for the desired key state, reporting the
   agent version
2. Non-Linux hosts stop here Windows agents register and heartbeat only
3. Diff the desired keys against /root/.ssh/authorized_keys;
   unchanged → write nothing
4. Changed → write a temp file, rename it over the real one, chmod 0600
```

## Service management

### Linux

Unit at `/etc/systemd/system/vantage-agent.service`, `Restart=always`, running
as root.

```bash
systemctl status vantage-agent
systemctl restart vantage-agent
journalctl -u vantage-agent -f
```

### Windows

A service registered through NSSM, or installed by the MSI that CI builds.

```powershell
Get-Service vantage-agent
Restart-Service vantage-agent
```

## Command-line flags

```
vantage-agent -generate-key
```

Generates a keypair locally. Normal operation takes no flags.

## Moving an agent to a new control plane

Change `server_url`, clear `agent_token`, set a fresh `pre_reg_token` from a new
enrolment, and restart. The old control plane still holds a server record that
will go `offline`; delete it there.

## Uninstalling

```bash
systemctl disable --now vantage-agent
rm -f /usr/local/bin/vantage-agent /etc/systemd/system/vantage-agent.service
rm -rf /etc/vantage
systemctl daemon-reload
```

Keys already written to `authorized_keys` remain on disk the agent is no
longer running to remove them. Revoke first if that matters.
