Installation and enrollment

What you deploy

VerOps Scout ships as proper installers — not a raw binary you place by hand. As of v0.3.0 there are two ways to get one:

• Preconfigured setup wizard (recommended, Windows) — downloaded from Inventory → Agents → "Deploy Scout". It embeds your organization's configuration and a limited-use enrollment token, so installing is the whole job: run it, click through, done.
• Generic installers — a Windows installer and a Linux tarball from the platform Downloads page (app.verops.io/resources, the Fleet Agents category). You supply the configuration after install.

Either way the agent is installed as a managed service that is registered and started immediately. An unconfigured agent simply idles and retries with clear log errors until you give it an enrollment token — nothing reports before it can authenticate. For a server you already run the Machine Agent — just enable its inventory module (see the Machine Agent docs).

Scout authenticates by enrollment only. From v0.6.0 the only credential a Scout accepts is a limited-use enrollment token, which it exchanges once for its own device credential. The org-wide ingest api_key and username / password login are gone, and an agent whose config still names one will not start. If you are upgrading an existing fleet, read Upgrading an existing fleet at the foot of this page first.

Preconfigured Windows setup wizard

In Inventory → Agents → "Deploy Scout", pick the platform and options and download a wizard built for your organization. The installer already contains a generated scout.toml (backend URL, org, group) and a limited-use enrollment token. Run it — silently for fleets — and the agent:

1. installs and registers the VerOpsScout service with automatic start and crash recovery, enabled and started with no manual step;
2. writes your configuration and, as of v0.6.1, restarts the service so that configuration is the one the agent runs with;
3. enrolls on first start: it exchanges the embedded token for its own revocable per-device credential (see Enrollment and device credentials);
4. appears in Inventory → Agents, in the group you chose, within minutes.

The restart in step 2 is what makes a freshly deployed machine enrol with your token and land in your fleet group on the first attempt. On earlier 0.6.x builds the service could come up on the packaged template's placeholder values instead, which showed up as an enrollment token that appeared not to work, or a machine that registered in the wrong group. If you saw either symptom, deploy v0.6.1.

Re-deploying an already-enrolled machine is safe and supported. The agent notices its enrollment token changed and re-enrolls, keeping its identity and history — so re-deploying is the normal way to move a machine to a new group, refresh its credential, or migrate it off a legacy configuration.

Generic Windows installer

VerOps-Scout-Setup-<version>.exe is an Inno Setup installer, branded with the VerOps icon. It installs the agent and registers the native Windows service VerOpsScout (LocalSystem) with automatic start and crash recovery, and starts it immediately. Until configured, the agent idles and retries — finish the setup:

1. Start Menu → "VerOps Scout" → "Configure Scout" — opens C:\ProgramData\VerOps\Scout\scout.toml. Set backend_url and an enrollment_token (minted under Inventory → Agents → Deploy Scout), and optionally a group.
2. Restart the service so it picks up the config — scout.toml is read once at startup: Start Menu → "Enable & Start Scout", or sc stop VerOpsScout & sc start VerOpsScout.
3. Confirm with "Scout Status" (STATE: RUNNING) and "View Scout Log" — watch it enroll and report.

For unattended / fleet rollouts, both installers support silent install:

VerOps-Scout-Setup-<version>.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

With the preconfigured wizard nothing else is needed. With the generic installer, push a pre-filled scout.toml to C:\ProgramData\VerOps\Scout\ (or use the SCOUT_* environment overrides) and restart the service.

Linux installer

verops-scout-linux-<version>.tar.gz contains an install.sh script and a systemd unit. It lays down /usr/local/bin/verops-scout, a config at /etc/verops/scout.toml, and the verops-scout systemd service — enabled and started as part of the install:

# Interactive: install, then configure and restart
sudo ./install.sh
sudo nano /etc/verops/scout.toml     # set backend_url + enrollment_token
sudo systemctl restart verops-scout

# One-shot: configure, enroll and start in a single command
sudo ./install.sh --org acme --enroll-token sce_xxxx --group Workstations

# Remove the agent, service, and config
sudo ./install.sh --uninstall

Follow the log with journalctl -u verops-scout -f. As on Windows, the config is read at startup — restart the service after editing it.

Where the agent finds its config

The verops-scout binary is service-aware — it runs under the Windows Service Control Manager and under systemd on Linux. It looks for its configuration in this order:

1. an explicit --config <path>;
2. otherwise the system config path — %ProgramData%\VerOps\Scout on Windows, /etc/verops on Linux;
3. otherwise a scout.toml next to the executable, then the current directory.

The installers simply place scout.toml in the system path for you.

Minimal scout.toml

The recommended enrollment uses a one-time enrollment token and lets central config drive what is tracked:

backend_url = "https://app.verops.io"

# Enrollment token (Inventory > Agents > Deploy Scout). Exchanged on first
# start for a private per-device credential; not needed afterwards.
enrollment_token = "sce_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Let VerOps manage what this agent tracks (the default).
use_central_config = true

# Enrollment hint: which Group this agent belongs to.
group = "Marketing"

# Local fallback only - used until the first successful central-config fetch.
interval_secs = 15
heartbeat_secs = 300

# Allow this machine to replace its own binary when the platform offers a
# newer release. OFF unless you write this line, and it still does nothing
# until an admin enables a release channel for the organization.
auto_update = false

Every key has a SCOUT_* environment-variable override (e.g. SCOUT_ENROLLMENT_TOKEN, SCOUT_GROUP, SCOUT_BACKEND_URL) — convenient for image-based or MDM-pushed deployments. There is no other credential: api_key, username and password are not valid Scout settings and their presence stops the agent from starting. The full model is in Enrollment and device credentials.

Running it

With the installers, the agent runs as a managed service — the Windows VerOpsScout service (LocalSystem, elevated, so per-app bandwidth is available) or the verops-scout systemd unit — started at install time and at every boot. The LocalSystem service also survives reboots and logoff.

If you instead want the agent in a user's interactive console session — the only way to detect foreground focus (activity level 3) — register a highest-privilege logon task pointing at the installed binary rather than relying on the session-0 service:

# Windows - highest-privilege logon task (interactive session -> activity level 3)
schtasks /create /tn VerOpsScoutLogon /sc onlogon /rl highest ^
  /tr "C:\Program Files\VerOps\Scout\verops-scout.exe" /f
schtasks /run /tn VerOpsScoutLogon

Verifying enrollment

On first start with an enrollment token the agent exchanges it for a device credential, then writes a line to its log like:

applied config 83c4c528: mode=targeted patterns=5 excludes=22 interval=15s heartbeat=300s

...then reports its first inventory. A report [full]: 0 apps line is correct when the targeted patterns match nothing currently running — it proves targeting works, not that the agent is broken. The device appears in Inventory → Agents with its enrollment credential listed.

Enrolling a device (no agent)

Tablets such as iPads cannot run a native agent. Their inventory is ingested MDM-style using an Inventory ingest API key — device identity, installed apps, and last-seen come in through your MDM. The device appears in the estate as a Device alongside agent-reported hosts. That key belongs to your MDM integration; it is not a credential a Scout can use.

Which version am I installing?

The current release is Scout v0.6.1 (the server-side collector, the Machine Agent, is at v0.5.0). Upgrading an already-enrolled agent needs no re-enrollment — the device credential survives, and the installer restarts the service for you. The full version history is in the product under Inventory → Agents → Release notes.

v0.6.1 makes the preconfigured installer restart the service after writing your configuration, so a freshly deployed machine enrols with your token and lands in your fleet group on the first try. v0.6.0 made enrollment the only way a Scout authenticates.

Automatic updates arrived in v0.5.0, so a fleet on v0.4.0 or older still needs one manual install to get moving. From v0.5.0 onward you can let the agents do it: add auto_update = true to scout.toml and have an admin enable a release channel under Inventory → Agents → Auto-update. Both switches are required, and both are off by default — see Automatic updates.

Upgrading an existing fleet

If any of your machines were configured with an org-wide ingest api_key, or with username / password, migrate them before you upgrade them. Those settings were removed from the agent in v0.6.0, and a v0.6.x Scout that finds one in its config refuses to start — it exits with a configuration error (EX_CONFIG, exit code 78) naming the file and each offending key, so the service shows the reason rather than going quietly silent.

• Scout v0.5.0 and earlier keep working against the platform unchanged, so there is no deadline and no estate-wide outage waiting for you. Pace the migration as you like — the only rule is that each machine is migrated before its agent is upgraded.
• Re-deploy from Inventory → Agents → "Deploy Scout" — the fastest route, and the one to prefer. The generated package carries a fresh enrollment token and no legacy keys; the machine re-enrolls and keeps its identity and history.
• Or hand-edit scout.toml: delete the api_key / username / password lines, add an enrollment_token, restart the service, and clear any SCOUT_API_KEY / SCOUT_USERNAME / SCOUT_PASSWORD environment variables your deployment sets.
• Find the machines that still need it under Inventory → Agents — workstations that have never enrolled are flagged there, and those are exactly the ones still authenticating the old way.

The Machine Agent is not affected by any of this: it still supports an ingest api_key for its inventory module, and its machine connection key is unchanged. Do not strip api_key out of a machine-agent config.

Tip: On Windows, run the agent elevated and in the user's interactive console session (a highest-privilege logon task does both) — elevation unlocks per-app bandwidth and an interactive session unlocks foreground-focus detection (activity level 3).