Configuration reference

Three sources, one precedence order

The agent reads settings from a TOML file, environment variables, and CLI flags. When the same setting comes from more than one place, the highest-priority source wins:

1. CLI arguments — e.g. --platform-url
2. Environment variables — e.g. AGENT_PLATFORM_URL
3. Configuration file — config.toml

Anything not supplied falls back to a built-in default.

Config file sections

[platform]

Key	Default	Description
url	http://localhost:8080	Base URL of the backend — https://app.verops.io for the hosted platform (self-hosted: typically http://<host>:9191).
connection_key	—	Authenticates the agent; sent as X-Machine-Key. Generate under Infrastructure → Machine agents → "Add agent".

[agent]

Key	Default	Description
name	machine-agent-01	Unique, stable per host — the hostname is a good choice.
environment	production	Label used to group agents in the UI.
heartbeat_interval_secs	30	Seconds between heartbeats. Each one reports metrics and retrieves pending commands.

[log_collector]

Key	Default	Description
max_lines_per_read	10000	Cap on lines read per log request — bounds memory on long files.
max_file_size_mb	100	Files larger than this are skipped entirely.

Environment variables and CLI flags

Env var	CLI flag	Overrides
AGENT_PLATFORM_URL	--platform-url	[platform] url
AGENT_CONNECTION_KEY	--connection-key	[platform] connection_key
AGENT_NAME	--agent-name	[agent] name
AGENT_ENVIRONMENT	—	[agent] environment
—	--config	Path to the TOML file (default config.toml).
—	--log-level	trace/debug/info/warn/error (default info).
—	--service	Run under the Windows Service Control Manager (v0.2.0+). Used in the service's binPath; the installers set it for you.
—	--log-file	Write logs to a file (e.g. C:\Program Files\VerOps\machine-agent.log) — essential when running as a Windows service with no console.

[inventory] (optional module)

The off-by-default inventory module has its own section — enabled, enrollment_token (preferred; env AGENT_INVENTORY_ENROLLMENT_TOKEN), state_path, group, use_central_config, cadence keys, plus [inventory.modules] switches (hardware / installed_software / users / network / patch_posture) and free-form [inventory.tags]. It authenticates separately from the connection key. All keys and behavior: Software inventory module.

One key in this section is worth calling out: auto_update (default false, v0.4.0+). It is the server's half of the two-key switch that lets the agent replace its own binary — it does nothing on its own, and nothing at all happens unless an admin has also enabled a release channel for the organization. Like the rest of the file it is read at startup, so restart the service after changing it. See Automatic updates.

Secrets belong in the environment: Don't commit connection_key. Provide it through AGENT_CONNECTION_KEY or --connection-key at deploy time. Under systemd, put it in a root-only drop-in (Environment=AGENT_CONNECTION_KEY=…).