ITAM / Endpoint Agent

Endpoint Agent

Deploy a lightweight agent on Mac, Windows, and Linux endpoints so Carlos can see live health, software inventory, and offline alerts without walking the floor with a spreadsheet.

Real-world scenario

Carlos Reyes · IT Admin at Bluewave Labs

Carlos tests agent builds on a local dev server, validates on staging, and rolls out to production. He needs one install command, one update command, and a safe way to switch environments without re-imaging laptops.

Before you begin

  • ITAM access and permission to manage agent tokens (My Organization → Configuration)
  • Node.js 22+ on target endpoints (installer checks this)
  • Outbound HTTPS from endpoints to your WorkVerge server URL

Overview

The WorkVerge endpoint agent is a small Node.js service that runs on employee laptops and desktops. After enrollment it sends heartbeats every 60 seconds, scans installed applications every 10 minutes, and polls for remote commands from the WorkVerge console.

In the product you manage agents from ITAM → Agent Discovery (fleet health) and from each device's Health tab. Enrollment tokens are created under My Organization → Configuration → Agent Tokens.

What Carlos gets after install

  • Online / degraded / offline status from live heartbeats
  • Installed app inventory synced to the device record
  • Remote commands: rescan apps, shell, update agent, uninstall app, check OS updates
  • Automation workflows when an agent goes offline (email, in-app alert, and more)

How it works

  1. Install with a one-time enrollment token (wva_…). The agent registers the device (or links to an existing record) and saves a JWT in ~/.workverge-agent/profiles.json on the endpoint.
  2. Run as a service: launchd on macOS, systemd on Linux, NSSM or a scheduled task on Windows. Manage it with workverge-agentctl on Mac/Linux.
  3. Update in place by re-downloading the agent bundle from the same server URL. Credentials and profiles are preserved; you do not re-enroll.
  4. Switch environments (dev / labs / prod) using named profiles. Each profile stores its own server URL and JWT.

Offline detection

WorkVerge marks an agent offline when no heartbeat arrives for about 2 minutes. The health sweep runs every 2 minutes and fires Endpoint Agent Offline workflows only on the transition from online to offline, not on every cron tick while already offline.

Command cheat sheet

macOS / Linux (after install)

workverge-agentctl status
workverge-agentctl update
workverge-agentctl profile list
workverge-agentctl profile use staging
workverge-agentctl config show

One-liner update (no local CLI required)

curl -fsSL https://workverge.bluewavelabs.io/api/atx/v1/agent/update.sh | bash

Documentation guides

Start here if you are new

Follow Install & Enroll on a test Mac or Linux machine pointed at http://localhost:3000 or your organization's WorkVerge URL, then read Environment Profiles before touching production.

Related articles