Features

Features

This page is a complete catalog of Vantyr's capabilities, grouped by area, with pointers to the underlying routes and APIs where helpful. For setup see Usage and Deployment; for environment variables see Configuration.

Warning: Vantyr includes powerful monitoring and remote-control capabilities. Use only on machines you own or manage, and only where you have handled consent, privacy, and security requirements. Several features (remote scripts, interactive terminal, internet blocking) are inherently high-risk and are gated behind roles and server config.

---

Global navigation

Area	Route / location	Purpose
Agents (overview)	/	Lists agents with online/offline status and shortcuts into each agent's detail view.
Rules	/rules	Unified hub for alert rules, app blocking, internet access, scheduled scripts, and the cross-agent Events feed.
Groups	/groups	Organize agents into groups; rules and policies can be scoped per group (admin).
Users	/users	Dashboard user and role management (admin).
Settings	/settings	Retention, URL categorization, agent-enrollment tokens, integrations, two-factor auth, and preferences.
Logs	/logs	Server-side / cross-agent log views (where implemented).

/notifications redirects to /rules (legacy path). Admin routes (/rules, /groups, /users) require the admin role.

---

Per-agent detail view

The agent detail page (/agents/:agentId) shows a header, a side-by-side live screen + vitals panel, and a two-level tab navigation: five primary sections, each with its own sub-tabs (driven by frontend/src/lib/agentTabNav.ts). Tabs are capability-aware - unsupported features (e.g. URL tracking on Linux, keystrokes on Wayland) render a blank/disabled state via CapabilityNotice.

Section	Sub-tabs
Activity	Timeline, Analytics
Telemetry	URLs, Keystrokes, Windows, Events
System	Specs, Software, Scripts, Files
Control	Control, Terminal, Logs
Settings	Settings

Activity

Sub-tab	Description
Timeline	Session-oriented history of foreground apps and windows with durations. "View in Timeline" from an alert event deep-links with a highlight.
Analytics	URL analytics: category mix over time, top sites, and browsing sessions (/api/agents/:id/analytics/...). Requires URL history and, for categories, URL-categorization data.

The live Screen + activity view (demand-driven MJPEG) is embedded at the top of the page alongside agent vitals; screen capture only starts when a viewer connects (see Live screen below).

Telemetry

Sub-tab	Description
URLs	Raw browser-URL history (Windows only; captured via UI Automation).
Keystrokes	Captured keystroke events, when keystroke capture is enabled. Not available on Wayland.
Windows	Foreground window-focus history (application + window title).
Events	Alert-rule hits for this agent (rule name, channel, matched snippet); some rows attach screenshot evidence.

System

Sub-tab	Description
Specs	Hardware / OS / agent-version metadata, plus the Resource health history charts (CPU / memory / disk).
Software	Installed-software inventory; operators can trigger a fresh collection run. Source varies by platform (Registry on Windows; dpkg/rpm/pacman/flatpak on Linux).
Scripts	Ad-hoc remote scripts - only if ALLOW_REMOTE_SCRIPT_EXECUTION=true on the server. This is remote code execution; keep off unless you trust the deployment.
Files	Remote file browser and downloads; typically starts under the user's Documents folder, with navigation to other drives.

Control

Sub-tab	Description
Control	Remote mouse/keyboard plus lock / restart / shutdown of the host. Role-gated: viewers receive telemetry but cannot send control commands. Links to internet-access policy in Rules.
Terminal	Interactive remote shell (ConPTY on Windows / PTY on Unix). Gated by operator role and ALLOW_REMOTE_SCRIPT_EXECUTION; per-session audited.
Logs	Tail selected Windows log channels / log sources forwarded by the agent (when available).

Settings (agent-scoped)

Per-agent options such as retention overrides, auto-update preferences, the local UI password (when used), and other agent-specific configuration exposed by the server.

---

Live screen

Screen capture is demand-driven to avoid constant overhead. Opening the live view (GET /api/agents/:id/mjpeg?session=<uuid>) increments a per-agent viewer refcount; crossing 0→1 sends start_capture to the agent, which streams JPEG Binary frames over /ws/agent. The server caches the latest frame and serves an MJPEG multipart stream; when the last viewer leaves (1→0), stop_capture is sent. Screen streaming works on Windows and Linux X11; Wayland requires a portal + PipeWire.

---

Remote control

From the Control tab, operators and admins can drive the endpoint:

• Mouse and keyboard input - forwarded over /ws/view → allowlist + RBAC check → the agent's input subsystem.
• Power actions - lock, restart, and shutdown the host.

All control commands are validated server-side against a strict allowlist and require the operator (or admin) role. Viewer-role users receive telemetry only.

---

Resource health history

The agent samples CPU, memory, and disk usage with a lightweight collector and streams a metrics frame on a 60-second ticker. The server persists these to the agent_metrics table and exposes bucketed averages via GET /api/agents/:id/metrics. The Specs tab renders dependency-free SVG area charts with selectable ranges (1h / 6h / 24h / 7d). Retention is governed by METRICS_RETENTION_DAYS (default 90; 0 disables). Resource metrics are available on Windows and Linux.

---

Interactive terminal

A live shell from the dashboard, opened in the Terminal sub-tab under Control. The frontend uses @xterm/xterm; it connects to GET /ws/terminal?agent_id=&cols=&rows=.

• Windows: one ConPTY shell per session (CreatePseudoConsole) spawning powershell.exe in the user session.
• Unix/Linux: a PTY shell.
• Gating: requires the operator role and ALLOW_REMOTE_SCRIPT_EXECUTION=true, enforced server-side.
• Routing & safety: output is routed to the single owning browser via per-session routing; terminal frames are never persisted and never broadcast to other viewers. Each session is audited (terminal_session started/ended).

The ConPTY path is compile-verified; treat it as experimental on real Windows agents.

---

System info & software inventory

• System info / Specs - CPU/GPU, memory, disk, OS, hostname, and agent version, collected by the agent and shown in the Specs tab.
• Software inventory - the installed-software list, collected on demand (operators can request a fresh CollectSoftware run). Inventory source is the Windows Registry, or dpkg/rpm/pacman/flatpak on Linux.

---

URL analytics & categorization

URL capture is Windows-only (UI Automation reads the active browser URL).

• Raw URLs - the URLs telemetry tab lists captured URLs as-is.
• Analytics - the Analytics tab derives a category mix over time, top sites, and browsing sessions from captured URLs (/api/agents/:id/analytics/url-categories, .../url-sites, .../url-sessions).
• URL categorization - server-side category lists, site→category mappings, and manual overrides are managed under Settings → URL categorization (/api/settings/url-categorization/*). The categorizer is the one server module with unit tests.

---

Rules hub (/rules)

The Rules page is a unified hub with five tabs. Rules can be scoped to all agents, a group, or a single agent.

Tab	Label	What it does
alert-rules	Alert Rules	Create alert rules across several channels - see Alerting & monitoring. Substring or regex match for content channels; threshold/duration for monitoring channels. Matches feed the Events feed and optional notifications.
app-blocking	App Blocking	Block executables/processes by pattern (the agent kills matching processes); optional schedules (time windows). Actions appear in Events and per-agent app-block views.
internet-access	Internet Access	Restrict outbound internet on the endpoint via firewall policy (Windows Firewall / nftables/firewalld on Linux via a helper). The agent's own connection to Vantyr stays allowed. Optional schedules.
scheduled-scripts	Scheduled Scripts	Server-side cron-style schedules that run scripts on agents at fire windows. Requires ALLOW_REMOTE_SCRIPT_EXECUTION=true and trusted operators.
events	Events	Cross-agent timeline: alert matches, app-block actions, scheduled-script runs, and related connection events, with filtering.

Deep links use query parameters, e.g. /rules?tab=internet-access.

---

Alerting & monitoring

The alert engine (server/src/alert_rules.rs) evaluates rules as telemetry arrives and fires through a shared notify hub with per-rule cooldowns. Alert-rule channels:

Channel	Trigger
url	A captured browser URL matches the pattern (substring or regex).
url_category	The categorized URL matches a target category.
keys	Captured keystroke content matches the pattern.
resource	Resource threshold - a metric (CPU/memory/disk) crosses a comparator/threshold (0–100%), optionally sustained for duration_secs. Evaluated on each metrics frame.
agent_offline	An agent has not been seen for N minutes. Evaluated by a periodic 60s task (no-op unless offline rules exist).

Additional behavior:

• Screenshot on match - content-channel matches can optionally attach a screenshot as evidence, viewable from the Events row.
• External notifications - matches fan out to every configured channel: email (SMTP), Slack, Discord, Microsoft Teams, Telegram, ntfy, Pushover, a generic webhook, and Home Assistant. Channels are configured by server environment variables (secrets stay on the server); Settings → Alert notification channels shows live status and a Send test button. See Notifications (and Home Assistant for the HA blueprint).
• Every match is recorded to alert_rule_events and surfaced in both the per-agent Events tab and the cross-agent Events feed.

---

Two-factor authentication (TOTP)

Opt-in per-user TOTP, layered on top of password login (OIDC SSO already covers MFA separately).

• Setup - Settings → Two-Factor card (GET /api/2fa/status, POST /api/2fa/setup|enable|disable). Enabling issues single-use recovery codes, shown once and stored Argon2-hashed.
• Login - after password verification, if TOTP is enabled the server returns 401 { totp_required: true }; the login page then prompts for a TOTP code or a recovery code.
• Enable/disable actions are audited.

---

Agent enrollment

Agents join through an approval-gated enrollment flow:

1. An operator generates a 6-digit pairing code or invite under Settings → Agent enrollment tokens.
2. The agent auto-discovers the server via mDNS (or is given the URL) and POSTs an enrollment claim with its stable install_id (+ optional pairing code) to rate-limited enroll routes.
3. On approval (auto for quick_pair/invite codes), the server issues a 256-bit per-device agent token, stored only as an Argon2 hash, which the agent uses as its /ws/agent bearer.

See Usage for the step-by-step.

---

Operations & administration

Feature	Description
Auto-update	The server can push set_auto_update so agents update themselves; per-agent preference in the agent Settings tab.
Retention controls	Age-based pruning for telemetry, resource metrics (METRICS_RETENTION_DAYS), and script-execution history (SCRIPT_EXECUTION_RETENTION_DAYS); configurable in Configuration.
RBAC roles	admin (full management), operator (control + scripts), viewer (read-only telemetry). Control and admin routes are role-gated.
Demo mode	A complete offline experience (npm run demo / VITE_VANTYR_DEMO_MODE) backed by scripted data - no server required.
Health & metrics	GET /healthz, GET /readyz, and an optional Prometheus GET /metrics endpoint.

---

Cross-platform support

Vantyr's agent targets Windows first; Linux support is experimental (X11 generally works better than Wayland). Capability summary:

Feature	Windows	Linux X11	Linux Wayland
Online / token auth	Yes	Yes	Yes
Resource metrics	Yes	Yes	Yes
System info / logs	Yes	Yes	Yes
Software inventory	Yes	Yes	Yes
Screen streaming	Yes	Yes	Portal + PipeWire
Remote mouse/keyboard	Yes	Yes	If supported (libei/portal)
Active window/app	Yes	Yes	Desktop-specific / limited
URL tracking	Yes	Browser extension	Browser extension
Keystroke capture	Yes	Possible	Not generally available
App / internet blocking	Yes	Helper	Helper
Terminal	ConPTY	PTY	PTY
Script execution	Yes	Yes	Yes

---

Feature ↔ API map (quick reference)

The REST surface is defined in server/src/api/mod.rs. Examples:

• Telemetry: GET /api/agents/:id/windows, /keys, /urls, /activity, /metrics
• URL analytics: GET /api/agents/:id/analytics/url-categories, .../url-sites, .../url-sessions
• Screen: GET /api/agents/:id/mjpeg, GET /api/agents/:id/screen
• Rules: /api/alert-rules, /api/app-block-rules, /api/internet-block-rules, /api/scheduled-scripts
• Two-factor: GET /api/2fa/status, POST /api/2fa/setup|enable|disable
• Terminal: GET /ws/terminal?agent_id=&cols=&rows=

Unauthenticated paths include GET /healthz, GET /readyz, GET /metrics (if enabled), GET /ws/agent (token-authenticated), and auth endpoints under /api/login and /api/auth/*. A dashboard session is required for all other /api/* routes and for /ws/view and /ws/terminal.