Skip to content

Usage

Jump to bottom
gladsonsam edited this page Jun 22, 2026 · 5 revisions

Usage

This is the operator's guide to Vantyr - signing in, managing users, enrolling Windows/Linux agents, navigating the dashboard, and driving the day-to-day monitoring and control features. For installation see Deployment; for the full feature catalogue see Features; for hardening see Security and OIDC.

1. First login (admin bootstrap)

Vantyr does not ship a default password. On first boot the server reads ADMIN_PASSWORD (or the legacy UI_PASSWORD) and bootstraps a single admin account. Release builds refuse to start without one of these set - see Configuration.

  1. Open the dashboard in a browser at your server origin (e.g. https://vantyr.example.com).
  2. Sign in with username admin and the value of ADMIN_PASSWORD.
  3. The dashboard calls POST /api/login; on success GET /api/me hands back a per-tab CSRF token (held in sessionStorage) that is attached to every mutating request. A 401 anywhere dispatches a session-expired event and returns you to the login screen.
  4. Change the bootstrap password immediately and consider enabling 2FA.

If OIDC/SSO is configured, a Sign in with SSO option also appears. Group claims map to roles via OIDC_ADMIN_GROUP / OIDC_OPERATOR_GROUP. See OIDC.

2. Creating users & roles

User management lives at /users (admin-only).

Role Can do
admin Everything: users, rules, groups, settings, enrollment, plus all operator/viewer abilities.
operator View telemetry and send remote-control commands (mouse/keyboard, power, terminal, scripts).
viewer Read-only: receives telemetry over the viewer WebSocket but cannot control agents.

To add a user:

  1. Go to Users → Add user.
  2. Set a username, initial password (minimum 6 characters - pick something stronger), and a role.
  3. Save. The user can change their own password and profile later.

Notes & guardrails:

  • The server enforces RBAC (user.is_admin() / user.is_operator()); the UI only mirrors it. Never rely on the UI alone - the server is the source of truth.
  • Anti-lockout protections prevent demoting/deleting the last admin and prevent deleting yourself.
  • Per-user identity linking (OIDC subjects) is managed from the same page.

3. Enrolling a Windows / Linux agent

Vantyr authenticates agents with a per-device 256-bit bearer token, issued at enrollment approval and stored server-side only as an Argon2 hash. The standard flow uses 6-digit pairing codes - no global shared secret to leak.

3.1 Generate a pairing code (dashboard)

  1. Go to Settings → Agent enrollment (/settings, admin-only).
  2. Create an enrollment code. You can set:
    • an expiry (default ~10 minutes),
    • a use count (single- or multi-use),
    • the approval mode (some code types quick_pair/invite auto-approve; standard codes require explicit admin approval).
  3. Copy the 6-digit code. Codes are stored only as SHA-256 digests, are single-use-decremented, and are revocable.

3.2 Install and run the agent

Windows uses a dual-process model: a Session 0 LocalSystem service owns the server WebSocket (and survives the lock screen), and a per-user companion does the actual capturing and shows the tray + settings window. See Deployment for the MSI install. Linux runs as a single headless direct-WebSocket process.

The agent connects to a WebSocket URL ending in /ws/agent, and requires wss:// (TLS) - plain ws:// is refused:

wss://192.168.1.10:9000/ws/agent
wss://monitor.example.com/ws/agent

On first run the agent generates a stable install_id, can auto-discover the server over mDNS on the LAN, and prompts for (or accepts) the pairing code.

To pair, the agent calls the public enrollment endpoints:

Step Endpoint What happens
Submit code POST /api/agent/enrollment/claims Agent posts the 6-digit code → server records a pending claim.
Poll GET /api/agent/enrollment/claims/:id Agent polls until the claim is approved/rejected.
(legacy single-shot) POST /api/agent/enroll One-step claim used by the optional enroll file.

These routes are rate-limited per IP (GovernorLayer, ~1/s) to slow brute-forcing of pairing codes.

3.3 Approve the pending claim (dashboard)

Unless the code auto-approves, an admin must approve the device:

  1. Go to Settings → Agent enrollment → Pending claims.
  2. Review the claimed machine (name, install id, platform).
  3. Click Approve (POST /settings/agent-enrollment-claims/:id/approve) or Reject (.../reject).
  4. On approval the server issues the per-device WS token; the agent stores it and reconnects authenticated to /ws/agent. The token travels in the Authorization header (never the URL).

What happens without pairing? The agent cannot connect - there is no anonymous agent access. (A legacy direct-enroll HTTP path now returns 410 Gone.) A machine with no valid token simply never appears in the Agents overview.

3.4 Optional: unattended enrollment file

To adopt a machine without typing the code in the agent UI, drop a plaintext enroll.json containing the 6-digit code under %ProgramData%\Vantyr\ (Windows). On startup the agent claims the code, receives its per-device token, writes its encrypted config, and deletes enroll.json.

3.5 Revoking an agent

From the agent's detail view (or via POST /agents/:id/revoke-credentials) you can revoke its credentials; the device must re-enroll with a fresh code.

4. Agent settings UI & local UI password

Windows: the companion process has no taskbar entry. Open its Tauri settings window with the global hotkey Ctrl+Shift+F12 (or the tray icon). From there you can set the server URL, display name, and enrollment details. Closing the window only hides it (the service keeps running); use Exit Agent to terminate. Config is stored at %ProgramData%\Vantyr\config.dat, encrypted at rest with DPAPI machine scope + app entropy.

Local UI password: to stop someone at the keyboard from opening the agent's settings window, set a local UI password. It can be managed globally (PUT /settings/local-ui-password) or per-agent (PUT /agents/:id/local-ui-password); the server pushes the password hash down to the agent (set_local_ui_password_hash). When set, the agent prompts for it before revealing settings.

Other agent settings pushed from the server and re-applied on every reconnect: auto-update policy, network policy (internet block), app-block rules.

5. Navigating the dashboard

Area Route Purpose
Agents overview / Grid/list of all agents with live status, vitals, and quick add.
Agent detail /agents/:id Per-agent two-level tabs (below).
Rules hub /rules Alert rules, app blocking, internet access, scheduled scripts, events. Admin-only.
Groups /groups Agent groups for scoping rules. Admin-only.
Users /users User & role management. Admin-only.
Settings /settings Retention, storage, URL categorization, enrollment, auto-update.
Logs / Audit /logs Operator action history.

5.1 Agent detail tabs

The agent view shows a header, a side-by-side live screen + vitals panel, then two-level tabs: five primary sections, each with sub-tabs.

Section Sub-tabs Content
Activity Timeline · Analytics Activity timeline (sessions, idle inference) and per-agent analytics.
Telemetry URLs · Keystrokes · Windows · Events Browsed URLs, captured keystrokes, foreground windows, and the agent's alert/block events.
System Specs · Software · Scripts · Files Hardware specs + resource history, installed software inventory, ad-hoc scripts, remote file browse.
Control Control · Logs Remote control surface and log-source tailing.
Settings Settings Per-agent retention, local UI password, auto-update overrides.

Tabs are capability-aware: Linux agents and feature-limited agents blank or disable sub-tabs they don't support (e.g. shells become sh/bash instead of powershell/cmd). Unknown legacy agents keep the original Windows behavior.

5.2 Alerts, Audit, Sessions/Timeline

  • Alerts / Events: the cross-agent Events feed (in the Rules hub) and each agent's Telemetry → Events sub-tab list alert-rule and app-block matches, with screenshots where captured.
  • Audit log (/logs): append-only record of admin/agent-affecting actions (with client IP). There is no delete/truncate endpoint.
  • Sessions / Timeline: the Activity → Timeline sub-tab reconstructs activity sessions and inferred idle periods from telemetry.

6. Using the Rules hub

The Rules page (/rules, admin) centralizes all policy. Rules can be scoped to agents or Groups.

Tab What it does
Alert rules Match telemetry channels (keystrokes, URLs, window titles…) against patterns; matches create events (and can fire external notifications to email, Slack, Discord, Teams, Telegram, ntfy, Pushover, webhooks, and Home Assistant - see Notifications). Per-(rule, agent) cooldown prevents spam.
App blocking Define blocked executables; the agent kills matching processes. View per-agent effective rules and known/seen exes.
Internet access Internet-block rules and schedule windows; enforced on the endpoint (netsh on Windows / nftables on Linux).
Scheduled scripts Scripts that run on a schedule, plus a manual Run now trigger.
Events Cross-agent feed of alert-rule and app-block matches.

To create an alert rule: open Rules → Alert rules → New, choose the channel, enter the match pattern, scope it (agent/group/global), save. Matches then appear in Events and in each agent's Telemetry → Events.

Scheduled scripts and Run now both respect the remote-execution kill-switch (below). With it off, the rule exists but never fires a script.

7. Interactive terminal & remote control

Both require an operator (or admin) role.

Remote control

From an agent's Control tab, operators can drive mouse/keyboard and send power commands (Lock / Restart / Shutdown / Wake-on-LAN). Control messages flow over the viewer WebSocket (/ws/view) and are validated against a strict per-command allowlist server-side before being forwarded to the agent. Viewers receive telemetry only and cannot control.

Interactive terminal

The interactive terminal (/ws/terminal) opens a live shell on the endpoint (ConPTY on Windows, PTY on Linux). It is double-gated:

  1. the user must be operator/admin, and
  2. the server must have ALLOW_REMOTE_SCRIPT_EXECUTION=true.

Each session is audited and its output is routed only to that session (never broadcast). Because it is an arbitrary-command shell, treat it as endpoint RCE - only enable it in trusted environments.

Kill-switch: ALLOW_REMOTE_SCRIPT_EXECUTION (default false) is the master switch for all code execution on agents - ad-hoc scripts, scheduled scripts, the manual Run now, and the terminal. Enabling it is effectively arbitrary code execution on every monitored machine. See Security.

8. Retention & clearing history

  • Global retention: Settings → Retention sets how long telemetry and auxiliary data (alert events, software snapshots, scheduled-script executions) are kept. A background prune job enforces it on an interval.
  • Per-agent retention: override the global policy per agent under the agent's Settings tab.
  • Clear history: purge a single agent's stored telemetry on demand via POST /agents/:id/history/clear (exposed from the agent's settings/controls).

9. HTTPS & secure-cookie notes

  • Behind a reverse proxy terminating TLS: forward X-Forwarded-Proto: https and set ENFORCE_HTTPS=true. Session cookies are then issued Secure + SameSite=None (the latter is required for cross-site WebSocket auth), so CSRF protection rests on the per-session X-CSRF-Token header check.
  • WebSocket upgrades: the proxy may forward X-Forwarded-Proto: wss; Vantyr treats wss like TLS for HTTPS enforcement.
  • Plain HTTP (labs only): set ENFORCE_HTTPS=false and do not force COOKIE_SECURE=true unless browsers actually reach the dashboard over HTTPS.
  • Agents always need wss:// even when the dashboard is served over plain HTTP
    • terminate TLS on the host (or a dedicated endpoint) agents connect to.

See Configuration and Deployment for full env details.

10. Demo mode

The dashboard ships an offline demo mode (npm run demo) that swaps the real API for seeded data and a scripted WebSocket stream - useful for exploring the UI without a backend. There is no live agent or control in demo mode.

11. Enabling 2FA on your account

Vantyr supports opt-in TOTP two-factor authentication per user.

  1. Open your account/profile area and choose Enable 2FA (POST /api/2fa/setup).
  2. Scan the QR code (or enter the secret) into an authenticator app (Google Authenticator, Aegis, 1Password, etc.).
  3. Confirm with a generated 6-digit code (POST /api/2fa/enable).
  4. Store the recovery codes shown - they are Argon2-hashed and single-use, your only fallback if you lose the authenticator.
  5. After this, login requires your password and a current TOTP code. Check status with GET /api/2fa/status; disable with POST /api/2fa/disable.

Enabling 2FA meaningfully raises account security above the 6-character password minimum - recommended for all admin and operator accounts.

See also: Features · Configuration · Security · OIDC · Notifications · Home Assistant · Deployment.

Vantyr repository · Issues · Wiki home

Home

Install and configure

Day to day

Integrations

Developers and security

Clone this wiki locally