Skip to content

Deploying Onagre Agents

Onagre offers multiple deployment methods for private agents, allowing flexible installation based on your infrastructure and operational constraints. Agents run checks from inside your private network and securely send results to the Onagre platform.

Quick pick

  • Install script – one command, fully automated setup on Linux. Recommended.
  • Linux manual – step-by-step systemd setup for full control.
  • Ansible – deploy at scale across your fleet.
  • Docker – fast to spin up, isolated, great for container-first stacks.
  • Windows service – native Windows service using the Service Control Manager (SCM).

Supported Deployment Methods

Linux

The fastest way to deploy an agent on Linux. A single command downloads the binary, creates the systemd service, and starts monitoring.

curl -fsSL https://d.onag.re/onagent.sh | sudo bash

The script auto-detects your architecture (x64, ARM, ARM64) and supports deploying multiple agents on the same host. It also provides built-in commands for listing, updating, and uninstalling agents.

See: Install script deployment for details and management commands.

Manual Setup

For teams that prefer full control over each step, the manual method walks through downloading the binary, writing the systemd unit file, and enabling the service.

See: Manual deployment for the complete step-by-step guide.

Ansible

Deploy agents across your entire fleet with a repeatable Ansible playbook. Handles architecture detection, binary download, service creation, and updates in a single run.

See: Ansible deployment for the playbook and role structure.

Docker

Run the agent in a container with a simple docker run and environment variables.

Highlights

  • Quick to test and iterate
  • Clean isolation and easy upgrades (pull a new image, recreate)
  • Works with Kubernetes and Docker Swarm

Typical workflow

  • docker run -d --name onagent --restart unless-stopped -e TOKEN=... onagre/agent:latest

See: Docker deployment for full examples and orchestration snippets.

Windows (Service via sc.exe)

Install the agent as a native Windows Service using the Service Control Manager.

Highlights

  • Native integration with Windows Services
  • Automatic start on boot, managed with sc and services.msc
  • Uses a machine-wide environment variable for the agent token (TOKEN)

Typical workflow

  • Download agent.exe to C:\Program Files\Onagre Agent\
  • Set the system environment variable TOKEN
  • Create the service: 
    sc.exe create OnagreAgent binPath= "\"C:\\Program Files\\Onagre Agent\\agent.exe\"" start= auto DisplayName= "Onagre Agent"
sc.exe start OnagreAgent

See: Windows (sc.exe) for the complete step‑by‑step guide, including update and uninstall.

Choosing the Right Method

Method Advantages Best for
Linux (systemd) Minimal overhead, predictable lifecycle, easy logs Dedicated Linux hosts/VMs, always‑on monitoring
Docker Fast rollout, isolated, easy rollbacks Containerized stacks, Kubernetes users
Windows (sc.exe) Native Windows service management Windows Server

General guidance

  • Prefer the method that matches your team’s existing operations playbook (systemd, Docker, or Windows Services).
  • For mission‑critical checks, run at least two agents in different failure domains (e.g., different VMs/hosts).
  • Keep agent binaries/images up to date for the latest fixes and features.

Networking & Security Considerations

  • Egress-only: The agent initiates outbound connections to Onagre; no inbound ports are required.
  • Firewall: Allow outbound HTTPS to the Onagre platform. If you use a proxy, configure it at the OS or container level.
  • Least privilege: Run with the minimal permissions necessary. On Linux, a dedicated user is possible if your checks allow it; on Windows, LocalSystem is simplest, but a service account can be used if the agent can access required resources.
  • Secrets: Store the agent token securely. On Linux use root-only perms on service files; on Windows restrict folder ACLs to Administrators and the service account.

Operations Checklist

-

Troubleshooting

  • Agent not visible in UI: Check that the TOKEN is correct and networking allows outbound HTTPS. Review logs (journalctl -u onagent on Linux; Event Viewer → Windows Logs → Application on Windows; docker logs onagent for Docker).
  • Service won’t start: On Linux, validate the service file and ExecStart path; run systemctl daemon-reload. On Windows, verify the binPath and that TOKEN is set system‑wide; check sc query OnagreAgent and Event Viewer.
  • Frequent restarts: Inspect agent logs for configuration errors; ensure the host clock is synchronized (NTP/Chrony/Windows Time).

What’s Next?

  • Proceed to the platform Configuration page to connect checks, tags, and notification channels.
  • Explore the How to monitor… guides for common services and patterns.