Skip to content

Deploying Onagre Agent on Windows (Service via sc.exe)

This guide shows how to install the Onagre Agent as a Windows Service using the Service Control Manager (sc.exe). Once installed, the agent runs in the background, starts automatically on boot, and reports to the Onagre platform.

Requirements - Windows Server 2012/2016/2019/2022 - An Agent Token from the Onagre platform - Outbound HTTPS connectivity to the Onagre API (through your proxy if applicable)

Download the Agent

The Onagre Agent is available for multiple architectures. Use the appropriate command for your system to download and install the agent:

https://d.onag.re/agent-win-x64.exe

https://d.onag.re/agent-win-x86.exe

Create a folder for the agent and place the binary there. The examples below use:

C:\Program Files\Onagre\agent.exe

If your organization uses software distribution (SCCM, Intune, etc.), push the binary to the target path with correct permissions.

Permissions (recommended)

mkdir "C:\Program Files\Onagre"
rem Grant Administrators full control and tighten inheritance if needed
icacls "C:\Program Files\Onagre" /inheritance:r
icacls "C:\Program Files\Onagre" /grant Administrators:(OI)(CI)F

Copy agent.exe into this folder.

Provide the Agent Token (Environment Variable)

The agent reads its token from the TOKEN environment variable. Set a system-wide environment variable so the Windows Service can inherit it:

setx TOKEN "<YOUR_TOKEN>" /M

Note: You must open a new Administrator command prompt after setting the variable so the updated environment is visible to subsequent commands.

Create the Windows Service

Use sc.exe to register the agent as a Windows Service. The simplest configuration runs under LocalSystem and starts automatically.

sc.exe create OnagreAgent ^
  binPath= "\"C:\\Program Files\\Onagre Agent\\agent.exe\"" ^
  start= auto ^
  DisplayName= "Onagre Agent"

Start the service:

sc.exe start OnagreAgent

Check status:

sc.exe query OnagreAgent

You can also use Services (services.msc) to confirm that the service is running.

Optional: Run Under a Dedicated Service Account

For environments with stricter separation of duties, you can run the agent under a domain or local account that has only the permissions it needs.

  1. Create or choose the account (e.g., DOMAIN\\svc-onagre).
  2. Grant Read & Execute on C:\Program Files\Onagre\ to that account.
  3. Ensure the account can reach the network resources the agent must check.
  4. Update the service to use this account:
sc.exe config OnagreAgent obj= "DOMAIN\svc-onagre" password= "<PASSWORD>"

If you rotate the password, repeat the sc.exe config command.

Verify Connectivity

  • Confirm the service is Running (sc query OnagreAgent).
  • In the Onagre web UI, the agent should appear online after a short delay.
  • If a proxy is required, configure it globally at the OS level or for the service account.

Logs & Diagnostics - Check Event Viewer → Windows Logs → Application for entries from the agent - If you temporarily run the agent interactively to test, open an elevated prompt and run: 

"C:\Program Files\Onagre\agent.exe"

Updating the Agent

  1. Stop the service: 
    sc.exe stop OnagreAgent
  2. Replace agent.exe with the new version (keep the same path).
  3. Start and verify: 
    sc.exe start OnagreAgent
sc.exe query OnagreAgent

For enterprise rollouts, distribute the updated binary with your software deployment tool.

Managing the Service

  • Status 
    sc.exe query OnagreAgent
  • Restart 
    sc.exe stop OnagreAgent
sc.exe start OnagreAgent
  • Disable auto-start 
    sc.exe config OnagreAgent start= disabled
  • Remove service (uninstall) 
    sc.exe stop OnagreAgent
sc.exe delete OnagreAgent

Firewall & Proxy Notes

  • Ensure outbound HTTPS is allowed from the host (to the Onagre platform endpoints).
  • If your environment enforces a proxy, configure it for the service account or system-wide. Validate with netsh winhttp show proxy and set with netsh winhttp set proxy if needed.

Troubleshooting

  • Service fails to start
  • Verify TOKEN is set at the machine level: reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v TOKEN
  • Confirm the path in binPath is correct and quoted properly
  • Check Event Viewer for startup errors
  • Agent not visible in UI
  • Verify outbound network access; confirm any proxy settings
  • Re-check the TOKEN value; restart the service after changes
  • Permission errors
  • If running under a service account, ensure it has Read & Execute on the agent folder and access to any monitored resources

Summary

You’ve installed the Onagre Agent as a native Windows Service using sc.exe. The service starts automatically, inherits the TOKEN from the system environment, and reports to the Onagre platform. Keep the binary updated and monitor logs for healthy operation.