Browse documentation

Installing the Endpoint Agent

↩ Getting Started

The Endpoint Agent is a small program you install directly on a Windows or macOS machine for deep, per-device monitoring — hardware and OS identity, CPU / RAM / disk stats, installed software, and (on Windows) services and OS events. Like the Site Collector, it only makes outbound connections.

Use the Endpoint Agent for laptops, workstations, and servers you want to monitor from the machine itself rather than over the network.

Before you start

Windows: Windows 10, Windows 11, or Windows Server. The agent is a single native .exe — no .NET runtime to install.
macOS: an Apple Silicon (arm64) Mac. The agent is a single native binary.
Administrator access to JOATOS to mint an enrolment key and download the binary.

If the download buttons are disabled, the endpoint agent hasn't been configured on your server yet. An administrator needs to set the ENDPOINT_AGENT_REPO and ENDPOINT_AGENT_TOKEN server settings first.

Step 1 — Mint an enrolment key

Go to Settings → Site Collectors and create an enrolment key.
This key is scoped to your organisation and lets new machines self-enrol on first run.

Step 2 — Download the agent

Go to Settings → Downloads and choose the card for your platform:

Windows Endpoint Agent → Download joatos-endpoint-agent.exe
macOS Endpoint Agent → Download joatos-endpoint-agent (macOS arm64)

Step 3 (Windows) — Install and start

Place the .exe on the target machine and create an agent.ini file next to it:

mode=cloud
apiUrl=https://your-joatos-api
enrolmentKey=<your-enrolment-key>

From an elevated PowerShell, install and start the service:

sc.exe create HydraEndpointAgent binPath= "C:\Program Files\JOATOS\endpoint-agent\joatos-endpoint-agent.exe" start= auto DisplayName= "JOATOS Endpoint Agent"
sc.exe start HydraEndpointAgent

Step 3 (macOS) — Install and start

Create agent.ini at /Library/Application Support/JOATOS/endpoint-agent/:

mode=cloud
apiUrl=https://your-joatos-api
enrolmentKey=<your-enrolment-key>

Make the binary executable and install it as a background service:

chmod +x joatos-endpoint-agent-macos-arm64
sudo ./install-daemon.sh --bin ./joatos-endpoint-agent-macos-arm64

If macOS blocks the binary with a Gatekeeper warning, clear the quarantine flag first:
```
xattr -dr com.apple.quarantine ./joatos-endpoint-agent-macos-arm64
```

What happens after install

On first run the agent self-enrols using the key, and JOATOS issues it a unique device token (stored securely on the machine).
JOATOS tries to match the machine to an asset by its serial number. If it can't match confidently, the machine goes to the endpoint review queue for you to confirm.
The machine then appears under Endpoints (or Servers if it runs a server OS), and its stats and inventory start flowing in.

Notes & tips

Re-running enrolment after a reinstall or re-image reconciles to the existing record instead of creating a duplicate.
Whether a host is treated as a server or an endpoint is decided from its detected OS, and can be changed later.

PreviousCreating your first site NextInstalling the Site Collector