Installing the Versus Collector Agent

What Is the Collector Agent?

The Versus Collector is a small standalone program that runs inside a network Versus can't reach directly — a lab, a customer datacenter behind NAT or a firewall, a segmented VLAN. It opens a single outbound connection to your Versus instance, holds it open, and executes device operations (reads and changes) that Versus dispatches to it — signed, verified, and scoped to exactly what it's allowed to touch.

Because the collector only ever dials out, it never needs an inbound firewall rule, a listening port, or elevated network privileges. That same property is what makes it installable without administrator or root rights on the machine it runs on — on any of the three platforms it supports.

Prerequisites

• A Windows, Linux, or macOS machine with network access to the devices you want to manage, and outbound HTTPS/TLS access to your Versus instance.
• The collector binary for your platform, provided by your Versus administrator or downloaded from Client Tools in the support portal.
• A one-time enrollment token, generated by your Versus administrator (see Getting an Enrollment Token below).

No administrator/root access, no installer, and no software prerequisites beyond the single binary itself — pick your platform below and the rest of this guide follows it.

Choosing the right download

Client Tools lists one collector bundle per operating system and CPU architecture. Download the one that matches the machine the collector will run on. Each archive contains the collector, its self-update supervisor, and a platform-specific README. Linux and macOS bundles are gzip-compressed tarballs (.tar.gz, which preserve the Unix executable bit); Windows bundles are ZIPs:

• Windows (Intel/AMD 64-bit): versus-collector-windows-amd64-<version>.zip
• Linux (Intel/AMD 64-bit): versus-collector-linux-amd64-<version>.tar.gz
• Linux (ARM 64-bit, e.g. Raspberry Pi / AWS Graviton): versus-collector-linux-arm64-<version>.tar.gz
• macOS (Intel): versus-collector-darwin-amd64-<version>.tar.gz
• macOS (Apple Silicon — M1/M2/M3/M4): versus-collector-darwin-arm64-<version>.tar.gz

Not sure of your architecture? On Linux/macOS run uname -m (x86_64 → amd64, aarch64/arm64 → arm64). On Windows, 64-bit Intel/AMD is amd64; use it unless you know the machine is ARM.

Extract the bundle

• Linux / macOS: tar -xzf versus-collector-<os>-<arch>-<version>.tar.gz (add -C <dir> to extract into a specific folder). The tarball preserves the executable bit; if the files lost it in transit, run chmod +x collector supervisor.
• Windows: right-click the ZIP → Extract All, or run Expand-Archive versus-collector-windows-amd64-<version>.zip -DestinationPath . in PowerShell.

Step 1 — Choose a Folder and Set the State Directory

The collector keeps its enrollment identity, credential vault, and local journal in a state directory. Pick a folder you own — never a system directory — and point VERSUS_STATE_DIR at it explicitly.

Step 3 — Get an Enrollment Token

Enrollment tokens are one-time-use (or limited-use), short-lived, and scoped to a specific site. Issuing one requires admin-level access to your Versus instance — specifically the collector.enroll permission, held by admin/network-admin roles. If that's not you, send this step to whoever administers Versus and ask them for the plaintext token and your instance's enrollment URL — that's the only thing you need to move on to Step 4.

Go to Versus Platform → Collector Fleet → Sites, find the site this collector will serve, and click Issue Token. Set how many collectors can enroll with it (Max uses), how long it stays valid (Expires in), and whether a new collector goes Active immediately or sits Pending until manually approved.

Click Issue Token and copy the plaintext value shown — it's displayed exactly once. Versus stores only its hash, so if you navigate away before copying it, it can't be recovered; you'd need to issue a fresh one. The same panel shows the exact--enroll-url/--enroll-token command to run in Step 4, pre-filled with your instance's actual URL.

Each site's tokens are also listed there (expand Tokens for <site>) — with status, how many uses are left, and a way to revoke one early if you issued it by mistake or it's no longer needed.

curl https://<your-versus-instance>/api/sites/ \
  -H "Authorization: Bearer <your-api-token>"

curl -X POST https://<your-versus-instance>/api/collector-tokens/ \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "<site_id>",
    "max_uses": 1,
    "ttl_hours": 24,
    "approval_mode": "auto"
  }'

Step 4 — Enroll and Connect

Step 5 — Verify the Connection

In Versus, go to Collector Fleet → Collectors. Your collector should appear with session state Active and its reported driver capabilities listed.

Already Installed? Starting, Restarting and Stopping

Once enrolled, the collector's identity lives in its state directory (VERSUS_STATE_DIR). To start it again — after a reboot, a logout, a crash, or because you stopped it — run the binary from its folder with no flags:

# Windows (PowerShell)
.collector.exe

# Linux / macOS
./collector

It reads the saved identity, reconnects to the gateway and logs session established; within a minute it shows Active under Collector Fleet → Collectors. Do not pass --enroll-url / --enroll-token again: the one-time token was consumed at enrollment, and a collector started with a token alongside an existing identity logs enrollment token supplied but this state dir already holds an enrolled identity — the token is IGNORED and carries on with the saved identity.

If you set the collector up as a service (recommended — see Keeping the Collector Running), start the service instead of the binary:

schtasks /Run /TN "Versus Collector"                      # Windows, Task Scheduler
nssm start VersusCollector                               # Windows, service (stop: nssm stop VersusCollector)
systemctl --user start versus-collector                  # Linux, systemd user unit (restart / stop / status likewise)
sudo systemctl start versus-collector                    # Linux, systemd system unit
launchctl kickstart -k gui/$(id -u)/io.versus.collector  # macOS, launchd
docker start versus-collector                            # Docker
supervisor -state-dir <state-dir> -collector-bin ./collector   # the supervisor by hand

To stop a collector running in a console, press Ctrl+C. Stopping is always safe: the collector pauses at its last checkpoint and resumes when started again.

Re-enrolling — for a new site, a collector that was revoked or deleted in Collector Fleet, or a machine move: stop the collector, point VERSUS_STATE_DIR at a fresh (or emptied) directory, get a new one-time token, and run the Step 4 enrollment command again.

Upgrading to a new version

Under the supervisor with self-update enabled there is nothing to do on the host: a published release shows as Update available on the collector in Versus and is applied automatically or after an administrator's approval, depending on the site's update policy — health-checked, with rollback. Otherwise download the new bundle from Client Tools, stop the collector, replace the binaries in place, keep the state directory, and start it again; it reconnects with its existing identity. The walkthrough with screenshots is in Collector Fleet → Upgrading collectors.

Certificate renewal

The collector's identity certificate is valid for 90 days and renews itself from day 60 (collector 0.4.15 or later): no re-enrollment, no restart, no new token. The log line identity certificate renewed confirms it, and the Collector Fleet page shows the next renewal window. To renew ahead of time, start the collector once with --renew-now. Only a certificate that has already expired needs a fresh enrollment token.

Troubleshooting a Collector That Won't Connect

Keeping It Running — Without Admin/Root Rights

Each platform has a way to keep a program running across logins that doesn't require elevated privileges — a system-wide service on any of the three still needs admin/root, so these options deliberately stay scoped to your own user session instead.

Troubleshooting