Skip to content
Docs

Install an agent

On this page
  1. Before you start
  2. 1. Create the agent in Onagre
  3. 2. Install it
  4. 3. Check that it is connected
  5. Operate your agents

Installing a private agent takes two steps: create it in Onagre to get its token, then install it on a machine of the network to monitor. If you are new to agents, read Public and private monitoring first.

Before you start#

  • A machine inside the network to monitor, always on: a small VM is enough. Linux (x64 or ARM64) is recommended; Windows (x64 or x86) and Docker (x64) are supported.
  • Outbound HTTPS (port 443) from that machine to api.onagre.io and to the Onagre Hub. Nothing inbound.
  • The Manager role, to create the agent in Onagre.

1. Create the agent in Onagre#

  1. Open Configuration → Agents and click New agent.
  2. Give it a Name that says where it runs — its host or its network, for example par1-prod-dc — and an optional Description.
  3. Choose its Type: Core (heartbeat and machine health only) or Advanced (runs your sensors). See Agent types.
  4. Click Create agent.

Onagre shows the agent's token, of the form ona1.<code>.<secret>. Copy it now: it is shown only once. It is the agent's only credential; keep it like a password.

New agent dialog: the name lyon-dc-agent, a description, the Advanced type selected rather than Core, and a notice that the token is only shown once.
Name the agent after where it runs and choose its type; the token comes next, only once.

Lost the token, or think it leaked? On the agent's Setup tab, Revoke and regenerate issues a new one and immediately invalidates the old one: update the agent with the new token so it can reconnect.

2. Install it#

Method Best for
Linux — automatic — recommended Linux servers and VMs: one command, an unprivileged systemd service, safe upgrades with rollback.
Linux — manual Linux hosts where you want to control every step. Same installation as the installer.
Docker Container hosts, Kubernetes, managed container platforms — and several agents on one host.
Windows Windows Server, as a native Windows service.
Ansible Deploying agents across a fleet of Linux hosts.

Every method does the same thing: run the agent binary with its token in the TOKEN environment variable. The agent needs no configuration file: it receives everything else from Onagre.

3. Check that it is connected#

After a few seconds, the agent shows Connected in Configuration → Agents, with its version and system.

Header and status of the agent par1-prod-dc: Connected, version 2.8.4.112 on Linux x64, low load, last heartbeat a few seconds ago, connected to the EU-FR-PAR-SCW-02 Hub.
Once the service is running, the agent shows as Connected with a fresh heartbeat.

On the machine itself, curl -s http://127.0.0.1:27520/ready answers {"status":"Ready"} once the agent is connected — see Health endpoints.

If it stays Never deployed:

  • read the agent's output (journalctl -u onagent, docker logs…): Waiting for API at … that never ends means https://api.onagre.io cannot be reached — check the firewall and the proxy; TOKEN is not valid means the token was mistyped or revoked: the agent then stops (exit status 78) until you replace it;
  • if /ready answers Hub stream not established, the Hub cannot be reached on port 443, or another agent already uses this token: one running agent per token.

Operate your agents#

  • Keep them up to date — a badge in the agents list shows when an update is available; each method page explains how to update.
  • Run two agents for critical checks — on two machines, so that one machine going down does not leave the network unwatched.
  • One token per agent — never copy a token to a second machine: create a second agent.
  • Collect the logs — see Agent configuration.