ITAM / Endpoint Agent

Update the Agent

Pull the latest agent code from your WorkVerge server without re-enrolling endpoints or losing dev/labs/prod profiles.

Real-world scenario

Carlos Reyes · IT Admin at Bluewave Labs

Carlos shipped a fix to agent heartbeat handling. He runs one update command on his test machine, then dispatches Update agent to the rest of the fleet from WorkVerge.

Before you begin

  • Agent already installed and enrolled
  • Endpoint can reach the server URL stored in the active profile
  • Node.js 22+ still present on the endpoint

Overview

Updates are in-place: the install directory is overwritten with a fresh bundle from the server, but enrollment credentials stay in ~/.workverge-agent/. You never need a new ENROLL_TOKEN for routine code updates.

The server exposes bundle version at GET /api/atx/v1/agent/version. Heartbeats send agentVersion so fleet health can flag endpoints running older builds.

Step-by-step

  1. 1

    Choose how to update

    Use curl on the endpoint, workverge-agentctl update locally, or Run command → Update agent from the device Health tab in WorkVerge.

  2. 2

    Agent stops and downloads the latest bundle

    The update script pulls bundle.tar.gz from the active profile's server URL (or SERVER_URL env). npm dependencies are refreshed in the install directory.

  3. 3

    Service restarts with same enrollment

    Profiles and JWT in ~/.workverge-agent are not touched. The agent resumes heartbeats with the new code version.

  4. 4

    Verify version in fleet

    Fleet health shows the new agentVersion. An Outdated chip clears when the version matches the server bundle.

Update methods

Method 1: curl one-liner (macOS / Linux)

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

Uses server URL from active profile or legacy config.json. Safe when piped to bash; the served script inlines required helpers.

Method 2: workverge-agentctl (after first update)

workverge-agentctl update
workverge-agentctl version

Method 3: Remote from WorkVerge UI

Open the device → Health tab → Run command → choose Update agent. The agent downloads the bundle from its connected server and restarts.

Windows

irm https://workverge.bluewavelabs.io/api/atx/v1/agent/update.ps1 | iex

Troubleshooting

Wrong server URL in update

If you use profiles, the update always pulls from the active profile's server. Switch with workverge-agentctl profile use dev before updating against localhost. See Environment Profiles.

Service stopped before update

If you ran workverge-agentctl stop first, the update script still works. It starts the service again when finished.

Related articles