Hypervisor

A self-hosted, lightweight dashboard for managing local services and scripts. Hypervisor acts as a daemon — start, stop, monitor, and inspect multiple applications from a single web interface.

---

Features

Process management

• Start and stop services via the dashboard or the service detail page
• Automatic restart on crash with configurable retry limits and cooldown
• Port conflict detection before spawning a process
• Graceful process-tree termination on stop (handles Windows and Linux child process hierarchies)

Monitoring

• Per-service CPU percentage and RAM (MB) with configurable polling rate
• TCP port reachability check displayed alongside metrics
• Live log streaming via Server-Sent Events with auto-scroll, pause/resume, and ANSI escape code stripping
• Port auto-detection: if no port is configured, the log stream is scanned for common "listening on :PORT" patterns and the stat box updates automatically
• Port Scanner page showing every listening TCP port on the machine, annotated with which ones Hypervisor manages and whether they are currently running

GitHub integration

• Import repositories directly from GitHub — Hypervisor clones them into a configurable local directory
• Pull and Fetch operations from the service detail page
• Ahead/Behind commit count displayed and cached in the database

Dashboard

• Real-time status cards with running/stopped/crashed state, metrics chips, and uptime timestamps
• Search by name and filter by status (running/stopped/crashed) and type (GitHub/manual)
• Add service modal with a toggle between manual configuration and GitHub import

Settings page

• Metrics polling rate (applied globally, persisted to database)
• GitHub repos root directory
• Auto-restart global limits: max retries and cooldown between attempts
• Password change (takes effect immediately without restart)
• Shutdown button — stops all services then terminates the Hypervisor process

Authentication

• Password-protected dashboard with signed session cookies
• Configurable session TTL

---

Tech stack

Layer	Stack
Backend	Python 3.11+, FastAPI, uvicorn
Database	SQLite
System	subprocess, psutil, socket

---

Requirements

• Python 3.11 or later
• git on PATH (required only for GitHub import features)

Install Python dependencies:

pip install -r requirements.txt

---

Running

python main.py

Open http://localhost:8000 in a browser. The default password is admin.

To expose the dashboard on your LAN (required for the Open button to resolve to the correct IP):

set HOST=0.0.0.0   # Windows
export HOST=0.0.0.0  # Linux/macOS
python main.py

---

Configuration

All options are read from environment variables at startup. Saved settings in the database take precedence over environment variables after the first save.

Variable	Default	Description
HYPERVISOR_PASSWORD	admin	Dashboard login password. Change before LAN exposure.
SECRET_KEY	random	Signs session cookies. If unset, sessions are invalidated on restart.
SESSION_TTL_HOURS	24	How long a login session lasts.
HOST	0.0.0.0	Bind address. Use 127.0.0.1 to restrict to localhost.
PORT	8000	HTTP port.
DB_PATH	hypervisor.db	SQLite database file path.
GITHUB_REPOS_DIR	github_repos	Root directory for cloned repositories.

Settings saved through the Settings page (polling rate, repos directory, auto-restart limits, password) are stored in the database and loaded on every startup, overriding the environment defaults.

---

Service configuration fields

Field	Required	Description
Name	Yes	Display label for the service.
Working directory	Yes	Absolute path used as the process CWD.
Command	Yes	Shell command to execute (python app.py, py app.py G:\Data).
Port	No	If set, used for TCP health checks and the Open button URL.
Environment variables	No	JSON object merged into the process environment.
Auto-restart on crash	No	Re-spawns the process after a non-zero exit, subject to global retry limits.

GitHub import

When using the GitHub mode in the add-service modal, provide a repository URL and an optional branch name. Hypervisor clones the repository under the configured GitHub repos directory, then uses the specified command to run it. Pull and Fetch operations are available from the service detail page.

---

Auto-restart behaviour

When auto-restart is enabled on a service and the process exits with a non-zero code:

1. Hypervisor waits for the configured cooldown (default 3 seconds).
2. It restarts the process and increments a per-session retry counter.
3. If the counter reaches the configured maximum (default 0 = unlimited), the service is marked permanently as Crashed and no further restart is attempted.
4. A manual Start from the dashboard or detail page resets the counter.

Global limits are configured in Settings and apply to all services with auto-restart enabled.

---

Windows notes

• Processes are spawned with shell=True and CREATE_NEW_PROCESS_GROUP so Ctrl+C in the Hypervisor terminal does not propagate to managed services.
• Process trees are terminated recursively via psutil (child processes are killed before the parent).
• The port scanner calls psutil.net_connections(). On some Windows versions this requires running as Administrator to see all processes; Hypervisor-owned ports are always visible.