Home

Vantyr wiki

Vantyr is a self-hosted endpoint monitoring & fleet-management system for Windows (and now experimentally Linux) endpoints. A native agent streams real-time telemetry - screen, foreground window/app, browser URLs, keystrokes, AFK/active state, software inventory, system info, and resource metrics - over WebSockets to a Rust/Axum/Tokio server backed by PostgreSQL. The server feeds a React 19 + TypeScript dashboard and adds remote control, app/internet blocking, scheduled remote scripts, an interactive terminal, URL-categorization analytics, and alerting.

Warning: This project is experimental and intended for testing, not as a hardened or supported product. Do not rely on it in production or for sensitive environments. Monitoring, remote control, and keystroke-related features carry inherent privacy and security implications; the codebase has not undergone professional security review and may contain bugs, weak defaults, or other issues that could expose data or systems. Linux agent support is experimental (X11 works better than Wayland; some capture/input features are unavailable on Wayland). Use at your own risk.

---

Documentation index

Page	What you will find
Deployment	Docker Compose, .env.example / .env, mDNS discovery, Traefik/TLS, health checks
Configuration	Environment variables (server, security, retention, Compose) - full reference
Environment template	Long .env-style block for advanced / non-Compose setups
Usage	Dashboard login, agent setup, HTTPS, enrollment, cookies
Features	Full feature catalog: agent tabs, Rules hub, analytics, terminal, 2FA
OIDC	OpenID Connect single sign-on for dashboard login
Notifications	Deliver alert matches to email, Slack, Discord, Teams, Telegram, ntfy, Pushover, webhooks
Home Assistant	Send alert-rule matches to Home Assistant (blueprint + mobile notifications)
Development	Local development, API and WebSocket overview, troubleshooting
Security	Vulnerability reporting, safe harbor, operator hardening

---

Architecture at a glance

Part	Role
Server (vantyr-server)	Rust + Axum/Tokio. Serves the built dashboard, the REST API under /api/*, the agent WebSocket /ws/agent, the viewer WebSocket /ws/view, the interactive-terminal WebSocket /ws/terminal, health checks /healthz and /readyz, and an optional Prometheus /metrics endpoint. Runs background tasks (alert engine, scheduler, offline checks, retention pruning).
PostgreSQL	Single source of truth: agents, telemetry, resource metrics, audit log, settings, rules, URL analytics, users, and 2FA secrets. Forward-only SQL migrations run automatically at server startup (server/migrations).
Agent (vantyr-agent)	Native Windows service + optional Tauri settings UI (experimental Linux build). Connects to the server with wss://, authenticates with a per-device token, streams telemetry, enforces app/internet policies pushed from the dashboard, and executes operator commands.

Real-time channels

Everything live flows through WebSocket channels on the server:

• /ws/agent - each agent connects here, authenticated by a per-device bearer token. Agent → server: telemetry frames (window_focus, url, keys, afk/active, metrics, software_inventory, MJPEG Binary frames, script_result, terminal_output, etc.). Server → agent: control and policy (start_capture/stop_capture, mouse/keyboard input, RunScript, lock/restart/shutdown, block-rule and network-policy updates).
• /ws/view - each dashboard browser tab connects here. The server sends an init snapshot then fans out every agent telemetry event. Viewer → server control commands are validated against a strict allowlist and RBAC-gated before being forwarded to the target agent.
• /ws/terminal - per-session interactive shell channel (ConPTY on Windows / PTY on Unix), routed to the one owning browser and never broadcast.

Production note: The Docker image builds the frontend into static files; you do not run Node in production for the dashboard.

---

Capabilities (current codebase)

• Activity timeline - Foreground app/window history with durations and deep-linkable highlights.
• Live screen - Demand-driven MJPEG; capture only runs while a viewer is watching.
• Remote control - Mouse/keyboard input plus lock, restart, and shutdown - role-gated (operators/admins, not viewers).
• Telemetry - Window focus, browser URLs (Windows), AFK/active transitions, and keystroke capture (when enabled).
• Resource health history - CPU / memory / disk time-series charts (1h / 6h / 24h / 7d).
• System info & software inventory - Hardware/OS/agent specs and the installed-software list (on-demand refresh).
• Interactive terminal - Live shell from the dashboard (ConPTY/PTY), gated and audited.
• File browser - Remote file navigation and downloads.
• URL analytics & categorization - Category mix over time, top sites, browsing sessions, and server-side category overrides.
• Rules hub (/rules) - Alert rules (URL, URL category, keystrokes, resource threshold, agent-offline), app blocking, internet-access (firewall) rules, scheduled scripts, and a cross-agent Events feed.
• Alerting & monitoring - Offline and resource-threshold alerts, optional screenshot-on-match, and notifications to email, Slack, Discord, Teams, Telegram, ntfy, Pushover, generic webhooks, and Home Assistant.
• Two-factor auth - Opt-in TOTP with single-use recovery codes; OIDC SSO also supported.
• Agent enrollment - Six-digit pairing codes and per-device WebSocket tokens (Argon2-hashed).
• Operations - Auto-update, retention controls, RBAC roles (admin/operator/viewer), and an offline demo mode.

See Features for the full, tab-by-tab catalog.

---

Source repository

Source code, README, SECURITY.md, docker-compose.yml, and .env.example live in the Vantyr repository on GitHub. This wiki is the extended operational guide.