Environment Profiles - WorkVerge Endpoint Agent Help

Real-world scenario

Carlos Reyes · IT Admin at Bluewave Labs

Carlos develops against a local dev server, validates on staging, and demos on production. He saves three profiles on his Linux box instead of reinstalling the agent each time.

Before you begin

Agent installed with workverge-agentctl (v1 after first update)
Valid enrollment token for each environment you add
Network access from the endpoint to each server URL

Overview

Each WorkVerge environment (dev, labs, prod) is a separate server with its own organization, devices, and JWTs. You cannot point one enrollment at multiple servers by editing only SERVER_URL.

Named profiles solve this for engineers and IT admins who test on one physical machine. Each profile stores serverUrl, agentToken, deviceAgentId, and deviceId for that environment.

Where profiles live

Profiles are stored on the endpoint at ~/.workverge-agent/profiles.json. Legacy single-file config.json is migrated automatically to profile default on first agent start after update.

Example profiles.json shape (tokens redacted in agentctl config show)

{
  "activeProfile": "dev",
  "profiles": {
    "dev": {
      "serverUrl": "http://localhost:3000",
      "agentToken": "…",
      "deviceAgentId": "…",
      "deviceId": "11753"
    },
    "staging": {
      "serverUrl": "https://staging.bluewavelabs.io",
      "agentToken": "…",
      "deviceAgentId": "…",
      "deviceId": "20401"
    }
  }
}

Add a profile

1
Create a token on the target environment
Log into dev, labs, or prod WorkVerge and create an agent token under My Organization → Configuration. Each environment has its own org and tokens.
2
Run profile add on the endpoint
Use workverge-agentctl profile add with --server-url and --enroll-token. The CLI enrolls against that server and saves a named profile locally.
3
Set active profile (optional)
Pass --set-active on add, or run workverge-agentctl profile use <name> later. The service unit is rewritten with the profile server URL and restarted.

Add staging profile

workverge-agentctl profile add staging \
  --server-url https://staging.bluewavelabs.io \
  --enroll-token wva_<staging-token> \
  --set-active

Switch profiles

1
List saved profiles
workverge-agentctl profile list shows each name, server URL, and an asterisk on the active profile.
2
Switch profile
workverge-agentctl profile use staging reconnects the agent to the staging server using that profile's saved JWT.
3
Confirm in WorkVerge
The device appears under the org where that profile enrolled. Carlos keeps separate enrollments per environment on the same physical machine when testing.

Switch back to local dev

workverge-agentctl profile use dev
workverge-agentctl status
workverge-agentctl config show

Remove a profile

workverge-agentctl profile remove staging deletes the saved credentials. It does not revoke the token on the server; revoke tokens in Org Configuration if needed.

Bluewave example

Carlos: three environments on one Linux workstation

dev → http://localhost:3000 (local WorkVerge instance)
staging → https://staging.bluewavelabs.io (pre-production validation)
prod → https://workverge.bluewavelabs.io (production org)

Before testing a workflow in staging he runs profile use staging. Before debugging agent code locally he runs profile use dev then workverge-agentctl update to pull the latest bundle from that server.