Installation and enrollment

Before you start

Requirement	Details
Operating system	Linux (x86_64) or Windows Server / Windows.
Memory	~20 MB RAM for the agent process at rest.
Network	Outbound access from the host to the VerOps backend. No inbound port is opened.
Connection key	Generated under Infrastructure → Machine agents → "Add agent" — the dialog also produces a full copy-paste install snippet for your platform. Sent on every request in the X-Machine-Key header.

1 — Get the package

As of v0.2.0 the agent ships as downloadable packages in Resources → Downloads (the Fleet Agents category):

• verops-machine-agent-linux-<version>.tar.gz — the binary, a systemd unit, and an install.sh;
• verops-machine-agent-windows-<version>.zip — the exe, a config template, and install-service.cmd.

(Building from source with a Rust toolchain still works: cargo build --release.)

2 — Install on Linux

The installer always registers, enables, and starts the verops-machine-agent systemd service:

tar -xzf verops-machine-agent-linux-0.5.0.tar.gz
cd verops-machine-agent-linux-0.5.0

# One-shot: configure and start in a single command
sudo ./install.sh --platform-url https://app.verops.io --connection-key <KEY>
# Optional: --name web-prod-01 --environment production

# Without flags a template config is seeded - edit it, then restart:
sudo nano /opt/verops/config.toml
sudo systemctl restart verops-machine-agent

# Remove the agent and service
sudo ./install.sh --uninstall

Files land at /opt/verops/machine-agent and /opt/verops/config.toml. Verify with systemctl status verops-machine-agent and journalctl -u verops-machine-agent -f.

3 — Install on Windows

From v0.6.1 Windows ships a setup wizard: VerOps-MachineAgent-Setup-<version>.exe. Run it as an administrator.

The wizard asks for your platform URL and connection key on a single page, then registers VerOpsMachineAgent as a Windows service with automatic start and crash recovery, and starts it.

An upgrade reads your existing configuration and pre-fills the page, so you are not retyping credentials. The previous file is kept as config.toml.bak.

Unattended install (GPO, Intune, SCCM, Ansible)

Pass the key on the command line and the configuration page is skipped, so the same command works interactively and silently:

VerOps-MachineAgent-Setup-<version>.exe /VERYSILENT /NORESTART ^
    /KEY=<connection key> ^
    [/URL=https://app.verops.io] ^
    [/ENV=production] ^
    [/NAME=%COMPUTERNAME%] ^
    [/LOG=C:\Temp\verops-install.log]

Parameter	Meaning
/KEY	Required. The connection key from Infrastructure → Machine agents → "Add agent".
/URL	Platform URL. Defaults to https://app.verops.io.
/ENV	Environment label shown in VerOps. Defaults to production.
/NAME	Agent name. Defaults to the computer name.
/LOG	Write a setup log — worth setting when a deployment fails.

A silent run without a key installs nothing and exits non-zero, so your deployment tool reports a failure instead of leaving a dead service behind on every machine.

Re-running the installer with a different /KEY updates the configuration and restarts the service. That is how you rotate a key across a fleet.

Where things are installed

Item	Path
Program	C:\Program Files\VerOps\MachineAgent\
Configuration	C:\ProgramData\VerOps\MachineAgent\config.toml
Log	C:\ProgramData\VerOps\MachineAgent\machine-agent.log

Configuration and logs live under ProgramData so they survive upgrades and uninstall, and so the service account can write to them.

The Start Menu group VerOps Machine Agent has entries to configure, start, stop, check status and open the log. Or from an elevated prompt:

sc query VerOpsMachineAgent
type "C:\ProgramData\VerOps\MachineAgent\machine-agent.log"

Configuration essentials

Every key and default is in the Configuration reference. The minimum:

[platform]
url = "https://app.verops.io"            # backend base URL
connection_key = "your-connection-key"   # from Infrastructure > Machine agents

[agent]
name = "web-prod-01"          # unique, stable — use the hostname
environment = "production"    # groups agents in the UI
heartbeat_interval_secs = 30  # check-in + metric cadence

Any connection setting can be overridden on the command line (--platform-url, --connection-key, --agent-name, --log-level) or via environment variables (AGENT_PLATFORM_URL, AGENT_CONNECTION_KEY, AGENT_NAME, AGENT_ENVIRONMENT).

Or run in Docker

Pass the key and URL as environment variables and mount log directories read-only — the agent only ever needs to read logs.

docker run -d --name verops-machine-agent \
  -e AGENT_CONNECTION_KEY=your-connection-key \
  -e AGENT_PLATFORM_URL=https://app.verops.io \
  -v /var/log:/var/log:ro \
  verops-machine-agent

4 — Verify enrollment

Open Infrastructure → Machine agents. Within one heartbeat interval the host appears as Connected, its row refreshing with CPU, memory, and uptime from the latest heartbeat.

Optional: feed Inventory from this server

The agent carries an off-by-default [inventory] module that reports this server's software inventory into the same estate VerOps Scout feeds — enrollment-token auth, separate from the connection key. See the inventory module.

Which version am I installing?

The current release is Machine Agent v0.5.0. Upgrading needs no re-enrollment — replace the binary and restart the service. Older agents keep working against the platform unchanged. The full version history is in the product under Inventory → Agents → Release notes.

Nothing about authentication changed in v0.5.0. The connection key still authenticates the core channel, and the [inventory] module still accepts an ingest api_key as well as the preferred enrollment token. If you are also migrating VerOps Scout — which from v0.6.0 refuses to start with an api_key in its config — do not apply that change here. The two agents differ deliberately, and the platform distinguishes them by the X-Agent-Kind header each one sends.

v0.4.0 was the first release that can update itself, so getting a fleet from v0.3.0 or older forward is still a manual install. From v0.4.0 onward, set auto_update = true under [inventory] and have an admin enable a release channel under Inventory → Agents → Auto-update — both switches are required and both are off by default.

Keep the key a secret: Anyone with the connection key can register an agent against your organization. Provide it via AGENT_CONNECTION_KEY, --connection-key, or the install script's flag at deploy time — never commit it to config.toml in version control.