ITAM / Endpoint Agent

Install & Enroll

Get the WorkVerge agent onto a laptop or desktop with a one-time enrollment token so Carlos can see it in fleet health without manual device entry.

Real-world scenario

Carlos Reyes · IT Admin at Bluewave Labs

Sophie Park's new Linux workstation needs the agent before Monday. Carlos creates a token in WorkVerge, SSHes in, and runs one curl command.

Before you begin

  • Enrollment token (wva_ prefix)
  • Server URL (e.g. https://workverge.bluewavelabs.io or http://localhost:3000 for local dev)
  • Node.js 22 or newer on the endpoint

Overview

Installation is a single script served by your WorkVerge instance. You pass ENROLL_TOKEN and SERVER_URL as environment variables. The agent enrolls once, saves credentials locally, and keeps running as a background service across reboots.

Step-by-step

  1. 1

    Create an enrollment token

    Go to My Organization → Configuration → Agent Tokens (or use ITAM → Agent Discovery → Add agent). Copy the token when shown; it is only displayed once.

  2. 2

    Open the Install wizard (optional)

    In Agent Discovery, the wizard walks you through platform selection, token creation, and the install command with your server URL pre-filled from the browser.

  3. 3

    Run the install command on the endpoint

    Paste the command in Terminal (Mac/Linux) or PowerShell as Administrator (Windows). The script downloads the agent bundle, installs npm dependencies, and registers a system service.

  4. 4

    Confirm enrollment in WorkVerge

    Within about a minute the device appears in Agent Discovery and on the device Health tab with status Online. Check hostname, platform, and agent version.

Install commands

macOS / Linux

curl -fsSL https://workverge.bluewavelabs.io/api/atx/v1/agent/install.sh \
  | ENROLL_TOKEN=wva_<your-token> SERVER_URL=https://workverge.bluewavelabs.io bash

Local development (Bluewave dev server)

curl -fsSL http://localhost:3000/api/atx/v1/agent/install.sh \
  | ENROLL_TOKEN=wva_<your-token> SERVER_URL=http://localhost:3000 bash

Windows (PowerShell as Administrator)

$env:ENROLL_TOKEN="wva_<your-token>"
$env:SERVER_URL="https://workverge.bluewavelabs.io"
irm https://workverge.bluewavelabs.io/api/atx/v1/agent/install.ps1 | iex

Do not sudo the curl pipe on Linux

Running sudo curl … | bash only elevates curl, not bash. For a system-wide install under /opt/workverge-agent, use curl … | sudo -E bash instead.

Install locations

  • macOS / Linux (user install): ~/.local/share/workverge-agent
  • macOS / Linux (system install): /opt/workverge-agent
  • Windows: C:\Program Files\WorkvergeAgent
  • Credentials: ~/.workverge-agent/profiles.json (migrated from legacy config.json)
  • CLI: workverge-agentctl in /usr/local/bin or ~/.local/bin

After install

Run workverge-agentctl status on the endpoint and open Fleet Management in WorkVerge to confirm the record.

Related articles