hyper2kvm

TUI Implementation Guide

Overview

The hyper2kvm TUI (Terminal User Interface) provides real-time monitoring of VM migrations with a beautiful orange theme. The implementation includes an intelligent 3-tier fallback system that works on any platform.

Orange Theme

The TUI features a vibrant orange color scheme:

Fallback System

Tier 1: Textual (Best Experience)

When textual>=0.47.0 is installed, you get the full-featured TUI:

Features:

Installation:

pip install 'hyper2kvm[tui]'

Keyboard Shortcuts:

Tier 2: Curses (Good Experience)

When Textual is not installed but curses is available (most Unix/Linux/Mac systems):

Features:

Keyboard Shortcuts:

Platform Support:

Tier 3: CLI (Universal Fallback)

When neither Textual nor curses is available (e.g., Windows without curses):

Features:

Platform Support:

Usage

Basic Usage

The TUI automatically selects the best available implementation:

from hyper2kvm.tui import run_dashboard

# Run with default settings (1 second refresh)
run_dashboard()

# Or customize refresh interval
run_dashboard(refresh_interval=2.0)

Check Dashboard Type

from hyper2kvm.tui import get_dashboard_type

dashboard_type = get_dashboard_type()
print(f"Using: {dashboard_type}")  # 'textual', 'curses', or 'cli'

Using Specific Implementation

Textual Dashboard

from hyper2kvm.tui import TEXTUAL_AVAILABLE

if TEXTUAL_AVAILABLE:
    from hyper2kvm.tui.dashboard import MigrationDashboard

    app = MigrationDashboard(refresh_interval=1.0)
    app.run()
else:
    print("Textual not installed. Install with: pip install 'hyper2kvm[tui]'")

Curses Dashboard

from hyper2kvm.tui.fallback_dashboard import CursesDashboard

dashboard = CursesDashboard(refresh_interval=1.0)
dashboard.run()

CLI Dashboard

from hyper2kvm.tui.cli_dashboard import CLIDashboard

dashboard = CLIDashboard(refresh_interval=2.0)
dashboard.run()

Programmatic Control

All dashboard implementations support the same interface:

from hyper2kvm.tui.widgets import MigrationStatus

# Create a migration status
migration = MigrationStatus(
    vm_name="web-server-01",
    hypervisor="vmware",
    status="in_progress",
    progress=0.45,
    current_stage="export",
    throughput_mbps=150.5,
    elapsed_seconds=120.0,
)

# Add to dashboard
dashboard.add_migration(migration)

# Update progress
dashboard.update_migration_progress(
    vm_name="web-server-01",
    progress=0.75,
    stage="convert",
    throughput_mbps=180.2,
)

# Log messages
dashboard.log_message("Export completed", "INFO")
dashboard.log_message("Validation failed", "ERROR")
dashboard.log_message("Migration successful", "SUCCESS")

# Remove migration
dashboard.remove_migration("web-server-01")

Migration Status Fields

@dataclass
class MigrationStatus:
    vm_name: str              # Name of the VM
    hypervisor: str           # Source hypervisor (vmware, azure, hyperv)
    status: str               # pending, in_progress, completed, failed
    progress: float           # 0.0 to 1.0
    current_stage: str        # export, transfer, convert, validate, etc.
    throughput_mbps: float    # Current throughput in MB/s
    elapsed_seconds: float    # Time elapsed
    eta_seconds: float        # Estimated time remaining (optional)
    error: str                # Error message if failed (optional)

Metrics Tracked

The dashboard automatically calculates and displays:

Performance Notes

Textual Dashboard

Curses Dashboard

CLI Dashboard

Troubleshooting

“Textual library is required” Error

Install Textual:

pip install 'hyper2kvm[tui]'
# or
pip install textual>=0.47.0

Curses Not Available on Windows

Windows doesn’t include curses by default. Options:

  1. Install windows-curses: 
    pip install windows-curses

  2. Use the CLI fallback (automatic)

  3. Install Textual for best experience: 
    pip install 'hyper2kvm[tui]'

Display Issues

If you see rendering issues:

  1. Ensure your terminal supports ANSI colors
  2. Try a different terminal emulator
  3. Check terminal size (minimum 80x24 recommended)
  4. For Textual, ensure terminal supports Unicode

Performance Issues

If the dashboard feels slow:

  1. Increase refresh interval: 
    run_dashboard(refresh_interval=2.0)  # Update every 2 seconds
  2. Limit number of displayed migrations
  3. Use curses or CLI fallback for lower resource usage

Examples

See the examples/ directory:

Architecture

hyper2kvm/tui/
├── __init__.py              # Auto-detection and fallback logic
├── dashboard.py             # Textual implementation (Tier 1)
├── fallback_dashboard.py    # Curses implementation (Tier 2)
├── cli_dashboard.py         # CLI implementation (Tier 3)
└── widgets.py               # Textual widgets and MigrationStatus

Design Philosophy

  1. Zero Configuration: Works out of the box on any platform
  2. Graceful Degradation: Best experience when possible, always functional
  3. Consistent API: Same interface across all implementations
  4. Orange Theme: Vibrant, energetic color scheme for better UX
  5. Real-time: Live updates for migration monitoring
  6. Lightweight: Minimal dependencies, optional enhancements

Future Enhancements

Potential future additions:

Contributing

To add new features or improve the TUI:

  1. Maintain compatibility with all three tiers
  2. Update the MigrationStatus dataclass if needed
  3. Keep the orange theme consistent
  4. Add tests for new functionality
  5. Update this documentation

License

LGPL-3.0-or-later

This site is open source. Improve this page.