← Back to home

Docs

How Vexo's workspaces, agents, and reports fit together.

Getting Started

From sign-up to your first live metrics takes about ten minutes.

1. Create your workspace

Sign up and name your workspace - you become its Admin automatically. If a colleague invited you, follow their invite link instead to join their workspace with the role they assigned you.

2. Download the agent for each machine you want to monitor

There are two ways to run it:

• Vexo Agent (for servers and fleets) - runs as a background service with no window: a systemd service on Linux, a Windows service on Windows. It starts with the machine and keeps reporting without anyone signed in.
• Vexo Desktop (for workstations and trying Vexo out) - a Windows app with a window and Start/Stop buttons. It reports while it's open.

Requirements for both:

• For GPU metrics: an NVIDIA GPU with its standard NVIDIA driver installed (the agent reads GPU data through the driver's NVML library). Machines without one still report CPU, memory, disk and network metrics.
• Outbound HTTPS (port 443) to https://vexo.yolosoft.net/. The agent only makes outbound connections - no inbound firewall rule is needed.
• One agent per machine, so a machine is never reported twice. Where the Vexo Agent service is installed it is the machine's agent: Vexo Desktop then doesn't monitor or enroll there.

3. Create an enrollment key

In Vexo, open Agents, click + Connect machines, choose Single machine, give the key a name (for example Render-Node-01) and click Create key. Copy the key shown (it starts with vxk_) - it is displayed only once, connects one machine and expires after a day if unused. To connect many machines with one key, choose Fleet instead (see below). Creating keys needs a role with the enrollment-key permission (Admins have it). The machine appears on the Agents page under its host name once it enrolls. A workspace has an agent seat for each machine its plan covers (2 on Free). A machine uses a seat once it enrolls and frees it when it's revoked; an unused key uses none. The Agents page shows how many seats are in use.

4. Install, enroll and start

Linux (.deb or .rpm)

sudo apt install ./vexo-agent_<version>_amd64.deb      # Debian / Ubuntu
sudo dnf install ./vexo-agent-<version>-1.x86_64.rpm    # RHEL / Rocky / Alma / Fedora
sudo vexo-agent enroll                                  # paste the key when asked
vexo-agent status

The package installs the agent to /opt/vexo-agent and starts the vexo-agent service, which runs as its own unprivileged account and waits until the machine is enrolled. It starts reporting within a few seconds of enrolling - no restart needed. Check it with systemctl status vexo-agent and journalctl -u vexo-agent. To enroll from a provisioning tool, pipe the key instead: echo "$VEXO_ENROLLMENT_KEY" | sudo vexo-agent enroll --if-not-enrolled.

Verifying a Linux package

Every .deb and .rpm is signed with Vexo's package signing key, so you can check a download came from Vexo and wasn't changed. Download the public key, signing-key.asc, then:

# .rpm - import the key once (with localpkg_gpgcheck=1 in /etc/dnf/dnf.conf, dnf then refuses unsigned ones)
sudo rpmkeys --import signing-key.asc
rpmkeys --checksig vexo-agent-<version>-1.x86_64.rpm        # must say: digests signatures OK

# .deb - the signature is the package's _gpgorigin member
mkdir vexo-check && cd vexo-check && ar x ../vexo-agent_<version>_amd64.deb
gpg --import ../signing-key.asc
cat debian-binary control.tar.* data.tar.* | gpg --verify _gpgorigin -   # must say: Good signature

Don't install a package that fails either check - download it again from this site.

Windows server (.msi)

Run the MSI (or install silently with msiexec /i VexoAgent-<version>-x64.msi /qn). It installs the Vexo Agent Windows service, which waits until the machine is enrolled. Then, in a PowerShell or Command Prompt opened with Run as administrator:

vexo-agent enroll        # paste the key when asked
vexo-agent status

The service starts reporting within a few seconds - no restart needed. Its log is C:\ProgramData\Vexo\logs\vexo-agent.log.

Vexo Desktop (Windows app)

Run the downloaded VexoDesktop.exe, click Settings, paste the key and click Activate, then click Start Monitoring. The credential is stored encrypted for your Windows user account, so you only enroll once per machine.

The agent isn't code-signed yet during early access, so Windows SmartScreen may warn you the first time: choose More info → Run anyway.

Checking and removing an agent

vexo-agent status shows the enrollment, the service's state and whether the machine is being monitored. To take a server out of Vexo, stop the service, run vexo-agent unenroll (with sudo, or as administrator on Windows), then revoke the agent on the Agents page.

Deploying to many machines (fleet keys)

One key can connect a whole fleet. On the Agents page, click + Connect machines, choose Fleet and create a key: give it a name, an expiry (1 day to 1 year) and, optionally, a machine limit. Copy the key (it starts with vxk_ and is shown only once) into your deployment tool's secret store.

# Windows - Intune, SCCM / ConfigMgr, Group Policy or any RMM tool (runs as SYSTEM)
msiexec /i VexoAgent-<version>-x64.msi ENROLLMENT_KEY=vxk_... /qn

# Linux - cloud-init, Ansible, or an image build script (as root)
apt-get install -y ./vexo-agent_<version>_amd64.deb
echo "$VEXO_ENROLLMENT_KEY" | vexo-agent enroll --if-not-enrolled

• One identity per machine. Each machine gets its own agent and its own credential, named after its host name. You can revoke machines one by one, as usual.
• Safe to run again. --if-not-enrolled (built into the MSI) leaves a machine untouched while Vexo still accepts its enrollment. If the enrollment was revoked, or replaced because the machine enrolled somewhere else, it enrolls again. If a machine enrolls again with a key, for example after a reinstall, it gets its existing agent back, not a duplicate. Machines are recognised by a one-way hash of the operating system's machine ID; the ID itself is never sent.
• Cloned machines. Build golden images so each clone gets its own machine ID: run sysprep on Windows, and empty /etc/machine-id on Linux (cloud images already do). Otherwise the clones share one agent.
• If a key leaks. Revoke it on the Agents page. Machines already enrolled with it keep reporting, and nobody can enroll with it anymore. A key can only add machines to your workspace; it can't read any data. Keys are limited to 300 new machines per minute.
• Failures are visible. If enrollment fails, the MSI install fails with exit code 1603 and is rolled back, so your deployment tool reports the machine. On Linux, the vexo-agent enroll step exits with a non-zero code.

Vexo Desktop also accepts a fleet key: paste it into Settings instead of a token.

5. Check it's reporting

Within the agent's reporting interval the machine appears as online on the Agents page, and its utilization, thermal and availability data flow into your dashboard and reports.

Troubleshooting

• "Enrollment failed" - the token was already used, expired, or its agent was deleted. Create a new token from the Agents page. With a fleet key: the key was revoked, expired or reached its machine limit. Check it on the Enrollment keys tab of the Agents page.
• "Can't write the enrollment" - run vexo-agent enroll with sudo (Linux) or from an elevated prompt (Windows).
• "Another Vexo Agent is already running" - only one agent may run per machine. Stop monitoring in Vexo Desktop or stop the service first.
• Service running but nothing reported - run vexo-agent status; if it says the service is waiting, its log says why (not enrolled yet, or revoked).
• No GPU data - check the NVIDIA driver is installed (nvidia-smi should run in a terminal).
• Agent shows offline - check the service is running (systemctl status vexo-agent, or the Vexo Agent service in Windows Services), or that Vexo Desktop is open with monitoring started, and that outbound HTTPS to Vexo isn't blocked by a proxy or firewall.
• Revoked agent - an Admin revoked this agent. Create a new token and enroll again; the service picks the new enrollment up by itself.
• Still stuck? Contact us.

Core Concepts

Workspaces & Tenants

A workspace is an isolated tenant: its agents, reports, members, and billing settings never cross into another workspace, even for a person who belongs to more than one. You can belong to several workspaces and switch between them at any time.

Roles & Permissions

Every member of a workspace holds one role - Admin, Member, or Viewer - which determines what they can see and do (for example, only certain roles can invite members, manage billing settings, or revoke an agent). Roles are set per workspace, so the same person can be an Admin in one workspace and a Viewer in another.

Agents & Enrollment Keys

An enrollment key is how a machine joins a workspace. A single-machine key connects exactly one machine; a fleet key connects many. Either way each machine becomes its own agent. Once enrolled, an agent authenticates with its own credentials, not the key, and reports metrics on the interval configured for it. Revoking an agent immediately invalidates its credentials; revoking a key stops new enrollments with it.

Metrics & Retention

Detailed metrics history is retained for a configurable period - 90 days by default - and purged automatically once it expires. The latest snapshot for each agent remains visible on the dashboard regardless of an agent's status, including one that has since been revoked.

Security

Signing in takes your password plus a one-time 9-digit code emailed to you, valid for 5 minutes with up to 3 attempts. The same two-factor pattern confirms other sensitive actions, like revoking an agent. Forgot your password? Reset it the same way - by email verification code, not a security question.

Reports

Every workspace draws from the same catalog of 30 built-in reports, grouped into cost & financial intelligence, utilization & performance, capacity planning & forecasting, reliability & hardware health, and resource contention diagnostics. See the full report catalog on the homepage, and Pricing for the plans.

Exporting a report to CSV

Every report has an Export CSV button. It downloads exactly what the page shows, with the agent, date range and time zone currently selected, as a file that opens in Excel, Google Sheets or LibreOffice. A report with several tables gives one file with a titled section per table; pages shown as charts or summary tiles export the underlying figures. Times are in UTC, and the page's navigation links are left out. A file only ever contains your current workspace's data.

Exporting needs two permissions: viewing the report, and exporting it. Admin, Member and Viewer can export every report they can view. Because exporting copies data out of Vexo, a custom role can be given a report without its export - the button is then hidden, and the download is refused.

Email Notifications

Vexo emails you when something needs your attention, so you don't have to keep checking:

• Machine offline alerts - when a machine stops reporting (it missed three reports in a row, and at least two minutes have passed). Machines that go offline together come in one email, and a machine that keeps dropping off is alerted at most once an hour.
• Weekly summary - once a week, the last 7 days of your workspace: how many machines are online, the estimated cost compared with the week before, and what needs attention, from the Executive Summary report. A workspace gets its first summary on the first send day after its first machine was enrolled.

Both are on by default. Turn either off in Email Notifications in the workspace menu; each workspace you belong to has its own choices. An email only goes to members whose role can see what it contains - the machine list for offline alerts, the Executive Summary for the weekly summary - and can change their own email notifications. Admin, Member and Viewer have all of these permissions. Someone who leaves the workspace, is deactivated or turns an email off before it is sent doesn't receive it.

Alert rules

A workspace can also be alerted about what Vexo finds in its machines' data. Each rule is off until someone who may change the workspace's billing settings (Admin) turns it on in Alert Rules in the workspace menu, and each has its own threshold:

• GPU too hot - a GPU's average temperature over the last 15 minutes is at or above the threshold (default 85 °C). Alerted again after 6 hours if it is still too hot.
• GPU throttling - a GPU's driver held its clocks back (by heat, a hardware slowdown or its power limit) in at least the threshold's share of its reports over the last 15 minutes (default 90%). Alerted again after 24 hours.
• Cost spike - a machine's true cost yesterday was at least the threshold above its own average of the days before (default 75%), by the Fleet Cost Anomaly Detector's rule. Each machine's day is alerted once.
• Budget at risk - at its pace so far, this month's GPU cost will end at least the threshold above last month's (default 15%). Checked from the 3rd day of the month, once the workspace has a whole previous month to compare with; alerted once a month.
• Idle machine - a machine reported on each of the last N days and its GPUs stayed below 5% busy all of those days (default 7 days). Alerted again after 7 days if it is still idle.
• Monthly budget - this month's GPU cost so far reaches the threshold's share of the workspace's monthly budget (default 80%), and again when it reaches the whole budget. Each is alerted once a month, and again if the budget is changed. Needs a monthly budget.

Several findings of one rule come in one email. An alert goes to the members whose role can open the report it links to and who can change their own email notifications; each member can turn each alert off for themselves in Email Notifications.

Notification channels: Slack, Teams and webhooks

Besides email, a workspace's alerts - a machine going offline and each alert rule it has on - can be posted where its team works. In Notification Channels in the workspace menu, someone who may change the alert rules (Admin) adds a channel and ticks the alerts it receives. Send test posts a test message at once and shows whether it arrived. The weekly summary stays an email.

• Slack - create an incoming webhook for the channel (a Slack app with Incoming Webhooks on) and paste its address, https://hooks.slack.com/services/....
• Microsoft Teams - in the channel, add the Workflows template Post to a channel when a webhook request is received and paste the address it gives you. (An older Office 365 connector address, ...webhook.office.com, also works while Microsoft still runs them.)
• Webhook - any https address, for PagerDuty, Opsgenie or your own tooling. Vexo shows the channel's signing secret once when it is added (New signing secret replaces it; the old one stops working at once).

A webhook receives a POST with a JSON body: id (the delivery's, the same on every retry), type (the alert: agent_offline, gpu_temperature, gpu_throttling, cost_anomaly, budget_risk, idle_machine, monthly_budget, or test), test, workspace_id, title, text, url (where to see it in Vexo) and created_at. Its headers carry X-Vexo-Delivery (the same id), X-Vexo-Event (the type) and X-Vexo-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of <t>.<raw body> keyed with the signing secret. To check a request, compute it over the raw body, compare in constant time, and refuse a t more than a few minutes old. For example, in Python:

import hashlib, hmac, time

def is_from_vexo(secret: str, signature_header: str, raw_body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in signature_header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(expected, parts["v1"])

Delivery: an answer of 2xx counts as delivered. A busy or failing receiver (408, 429, 5xx) or no answer within 10 seconds is retried after 1, 5 and 15 minutes, 1 hour and 3 hours, then given up. An address that answers any other 4xx (a removed Slack or Teams webhook answers 404 or 410) or a redirect is given up at once - fix the address. Each channel shows how its latest delivery went. Rarely, a retry can deliver an alert twice; a webhook can drop the repeat by its id. A channel's address must be a public https address on a host name: Vexo never connects to private, loopback or link-local addresses, whatever a name resolves to. Addresses and secrets are stored encrypted, and the page shows only the end of an address.

Audit log

Workspace admins can see who did what in the workspace, and when, on Audit Log in the workspace menu: invitations sent, withdrawn, accepted or declined, role changes, members removed or leaving, accounts deactivated by Vexo support, machines enrolled (and with which enrollment key), revoked, renamed or changed, enrollment keys created or revoked, billing settings, the monthly budget, GPU hourly rates, alert rules, notification channels, and every report or audit log export. Each entry has its time (UTC), who did it, what it was done to, the details, and the IP address the request came from. Filter by kind, period (up to 366 days at a time) and text, and download what the filters match as CSV. Entries are kept for as long as the workspace exists and can't be changed or deleted, not even by an admin. Viewing and exporting are separate permissions, both given to the ADMIN role.

Monthly budget

A workspace can set what it means to spend on GPU true cost - electricity plus its GPU hardware rates - each calendar month (UTC), in its billing currency, in Billing Settings. Changing it takes its own permission (Admin by default). The Executive Summary and the Fleet Cost Forecast then show this month's spend against it and where the month is heading at its pace so far (from the 3rd day of the month), and the forecast's budget risk means reaching that budget. Without a budget, the forecast can only guess a risk from how fast the cost grows.

Need more help?

Can't find what you're looking for? Contact us and we'll help you out.