VerOpsDocs
Get started
Docs / Network

Install the network agent

Register an agent under Network → Agents to get its connection key, install it with the Windows setup wizard or the Linux tarball, verify it registered, and know which ports it uses. Current release 0.3.0.

networkagentinstallinstallationinstallerwizardconnection-keywindowslinuxservicesystemdportsfirewall0.3.0

Before you start

  1. Where to put it. An agent measures the network from where it runs. Put the first one at the vantage point whose experience you care about — the branch whose users complain, the VPC the application lives in — not on the platform's side of the path. A second agent somewhere else turns on the mesh and lets you tell "the path is bad" from "the destination is bad".
  2. A machine to run it on. Windows 10 / Server 2016 or newer (x64) with administrator rights, or any 64-bit Linux with systemd — the Linux binary is statically linked and has no glibc requirement. Steady state is a few percent of one core and tens of megabytes of memory. A VM or a small container host is fine; it does not need to be dedicated.
  3. Outbound HTTPS from that machine to your platform URL (https://app.verops.io unless you run your own). Nothing needs to reach the agent from the internet; the agent registers, then polls.
  4. Raw-socket privileges. ICMP ping, traceroute and MTU discovery need raw sockets. The installers arrange this — the Windows service runs as LocalSystem, the Linux unit as root with a documented least-privilege alternative — so you only need to know it if you plan to run the binary some other way.
Servers already running the Machine Agent: that is a different agent for a different job (host metrics, logs, inventory). The network agent does not replace it and does not conflict with it — install both where you want both.

Step 1 — Register the agent and get its connection key

Every agent authenticates with its own connection key, created when you register it in the platform:

  1. In app.verops.io open Network → Agents and click Deploy New Agent.
  2. Give it a name humans recognise (lon-branch-1, prod-vpc-eu), and optionally a description, region, environment, mesh group and tags. Region and environment are labels used to group agents in the views and the mesh; they are not validated against anything.
  3. Click Register & Generate Key. The key — it starts with na_ — is shown once. Copy it now; the platform stores only a hash. If you lose it, Rotate key on the agent's card issues a new one and invalidates the old.
Watch out: the name is what shows up in every test result, the topology and the alerts. agent-1 paged at 3am tells you nothing; lon-branch-1 tells you which office to call.

Step 2 — Download the installer

Both packages are under Resources → Downloads, category Collector:

Package File What it is
VerOps Network Agent (Windows) VerOps-Network-Agent-Setup-<version>.exe A setup wizard. Asks for the key, writes the config, registers and starts the service. Also installs unattended from the command line.
VerOps Network Agent (Linux) verops-network-agent-linux-<version>-x86_64.tar.gz A static binary, install.sh, a systemd unit and a commented config example.

The current release is 0.3.0. Each package's page lists its SHA-256 so you can verify the download.

Step 3a — Install on Windows

  1. Run VerOps-Network-Agent-Setup-<version>.exe and approve the administrator prompt.
  2. On the Configuration page enter the Platform URL (default https://app.verops.io) and paste the Connection Key from step 1. Next stays disabled until the key is filled in — the agent exits immediately without one, so the wizard refuses to register a service that cannot start. Agent name defaults to the computer name; region and environment are optional.
  3. Leave Start the VerOps Network Agent now checked and click Install.

The wizard installs to C:\Program Files\VerOps\Network Agent\, writes C:\ProgramData\VerOps\Network Agent\config.toml with the values you entered, registers the VerOpsNetworkAgent service (LocalSystem, automatic start, restart on failure) and starts it. Allow network-agent.exe through the firewall if Windows prompts.

Unattended / fleet install — pass the same values on the command line and no windows are shown:

VerOps-Network-Agent-Setup-<version>.exe /VERYSILENT ^
    /ConnectionKey=na_xxxxxxxx ^
    /PlatformUrl=https://app.verops.io ^
    /AgentName=%COMPUTERNAME% /Region=eu /Environment=production

Add /NoStart to install and register the service without starting it. A silent run with no key installs nothing and exits non-zero, so a mis-templated policy deploy fails loudly rather than leaving a dead service on every machine.

Step 3b — Install on Linux

tar xzf verops-network-agent-linux-<version>-x86_64.tar.gz
cd verops-network-agent-linux-<version>-x86_64

# One shot: install, configure, enable and start
sudo ./install.sh --connection-key na_xxxxxxxx \
                  --agent-name lon-branch-1 --region eu --environment production

This places the binary at /usr/local/bin/verops-network-agent, the config at /etc/verops/network-agent.toml, and the verops-network-agent systemd unit, enabled and started.

Run install.sh with no flags and the service is installed but left disabled until you configure it — edit the two required values under [platform] in /etc/verops/network-agent.toml, then:

sudo systemctl enable --now verops-network-agent

The unit runs the agent as root because ping, traceroute, MTU discovery and ARP discovery need raw sockets. If your policy forbids that, the unit file itself documents the least-privilege alternative: a dedicated system user plus CAP_NET_RAW, CAP_NET_ADMIN and CAP_NET_BIND_SERVICE granted ambiently — everything keeps working without full root.

Step 4 — Verify it works

  1. The service is running. Windows: Start Menu → VerOps Network Agent → Agent Status reports STATE: RUNNING. Linux: systemctl status verops-network-agent.
  2. It registered. The log — View Agent Log on Windows, journalctl -u verops-network-agent -f on Linux — shows Agent registered successfully shortly after start. Locally, curl http://127.0.0.1:9877/health answers from the agent's own health endpoint (loopback only).
  3. The platform sees it. Network → Agents shows it online within a heartbeat (30 seconds by default), with the hostname, address, agent version and capabilities it reported on connection. The tab's badge counts online agents against registered ones.

Then create a test from it. If it never registers or keeps restarting, Troubleshooting lists the causes in the order they actually happen.

Ports and firewall

Direction Port Needed when
Outbound TCP 443 to the platform URL Always — registration, heartbeats, test assignments, results.
Agent ↔ agent TCP 9876 ([mesh] listen_port) Mesh measurements between agents. Only between your own agents; bind it to a private or VPN address if the host has a public interface.
Inbound UDP 162 ([snmp] port) Only when the SNMP trap listener is enabled and devices send traps to this agent.
Inbound UDP 2055 ([netflow] port) Only when the NetFlow collector is enabled and routers export to this agent.
Local TCP 9877 on 127.0.0.1 Always — the health endpoint. Never exposed off the host.

Upgrading and removing

Upgrade by installing the newer package over the old one. On Windows the wizard reads the existing config.toml, pre-fills the key and keeps every setting you customised, so you click through. On Linux install.sh never overwrites an existing /etc/verops/network-agent.toml; it replaces the binary and unit and restarts the service. The connection key is unchanged, so the agent keeps its identity, history and test assignments.

Remove with Settings → Apps → VerOps Network Agent → Uninstall (or unins000.exe /VERYSILENT) on Windows, and sudo ./install.sh --uninstall on Linux. Both keep the configuration; add /purge or --purge to delete it too. Then Delete Agent under Network → Agents so its key can no longer be used.

Next steps