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

  • Linux service (systemd) – persistent, lightweight, easy to manage with systemctl.
  • Docker container – fast to spin up, isolated, great for container-first stacks and orchestrators.
  • Windows service (sc.exe) – native Windows service using the Service Control Manager (SCM).

Supported Deployment Methods

Linux (System Service)

Run the agent as a systemd service for stability and automatic start at boot.

Highlights

  • Predictable lifecycle via systemctl (start/stop/restart/status)
  • Configuration via environment (e.g., TOKEN) and/or config file
  • Works on Debian/Ubuntu and most systemd-based distros

Typical workflow

  • Download the binary to /usr/local/bin/agent and make it executable
  • Create /etc/systemd/system/onagent.service
  • systemctl daemon-reload && systemctl enable --now onagent

See: Linux deployment for full commands and service file template.

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.