clonebox 0.1.9__py3-none-any.whl → 0.1.10__py3-none-any.whl

clonebox/cli.py

@@ -445,7 +445,72 @@ def cmd_start(args):
             return
 
     cloner = SelectiveVMCloner(user_session=getattr(args, "user", False))
-    cloner.start_vm(name, open_viewer=not args.no_viewer, console=console)
+    open_viewer = getattr(args, "viewer", False) or not getattr(args, "no_viewer", False)
+    cloner.start_vm(name, open_viewer=open_viewer, console=console)
+
+
+def cmd_open(args):
+    """Open VM viewer window."""
+    import subprocess
+    
+    name = args.name
+    user_session = getattr(args, "user", False)
+    conn_uri = "qemu:///session" if user_session else "qemu:///system"
+    
+    # If name is a path, load config
+    if name and (name.startswith(".") or name.startswith("/") or name.startswith("~")):
+        target_path = Path(name).expanduser().resolve()
+        config_file = target_path / ".clonebox.yaml" if target_path.is_dir() else target_path
+        if config_file.exists():
+            config = load_clonebox_config(config_file)
+            name = config["vm"]["name"]
+        else:
+            console.print(f"[red]❌ Config not found: {config_file}[/]")
+            return
+    elif name == "." or not name:
+        config_file = Path.cwd() / ".clonebox.yaml"
+        if config_file.exists():
+            config = load_clonebox_config(config_file)
+            name = config["vm"]["name"]
+        else:
+            console.print("[red]❌ No VM name specified and no .clonebox.yaml in current directory[/]")
+            console.print("[dim]Usage: clonebox open <vm-name> or clonebox open .[/]")
+            return
+    
+    # Check if VM is running
+    try:
+        result = subprocess.run(
+            ["virsh", "--connect", conn_uri, "domstate", name],
+            capture_output=True, text=True, timeout=10
+        )
+        state = result.stdout.strip()
+        
+        if state != "running":
+            console.print(f"[yellow]⚠️  VM '{name}' is not running (state: {state})[/]")
+            if questionary.confirm(
+                f"Start VM '{name}' and open viewer?", default=True, style=custom_style
+            ).ask():
+                cloner = SelectiveVMCloner(user_session=user_session)
+                cloner.start_vm(name, open_viewer=True, console=console)
+            else:
+                console.print("[dim]Use 'clonebox start' to start the VM first.[/]")
+            return
+    except Exception as e:
+        console.print(f"[red]❌ Error checking VM state: {e}[/]")
+        return
+    
+    # Open virt-viewer
+    console.print(f"[cyan]Opening viewer for VM: {name}[/]")
+    try:
+        subprocess.run(
+            ["virt-viewer", "--connect", conn_uri, name],
+            check=True
+        )
+    except FileNotFoundError:
+        console.print("[red]❌ virt-viewer not found[/]")
+        console.print("Install with: sudo apt install virt-viewer")
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]❌ Failed to open viewer: {e}[/]")
 
 
 def cmd_stop(args):
@@ -924,6 +989,217 @@ def cmd_import(args):
             shutil.rmtree(temp_dir)
 
 
+def cmd_test(args):
+    """Test VM configuration and health."""
+    import subprocess
+    import json
+    
+    name = args.name
+    user_session = getattr(args, "user", False)
+    quick = getattr(args, "quick", False)
+    verbose = getattr(args, "verbose", False)
+    conn_uri = "qemu:///session" if user_session else "qemu:///system"
+    
+    # If name is a path, load config
+    if name and (name.startswith(".") or name.startswith("/") or name.startswith("~")):
+        target_path = Path(name).expanduser().resolve()
+        config_file = target_path / ".clonebox.yaml" if target_path.is_dir() else target_path
+        if not config_file.exists():
+            console.print(f"[red]❌ Config not found: {config_file}[/]")
+            return
+    else:
+        config_file = Path.cwd() / ".clonebox.yaml"
+        if not config_file.exists():
+            console.print("[red]❌ No .clonebox.yaml found in current directory[/]")
+            return
+    
+    console.print(f"[bold cyan]🧪 Testing VM configuration: {config_file}[/]\n")
+    
+    # Load config
+    try:
+        config = load_clonebox_config(config_file)
+        vm_name = config["vm"]["name"]
+        console.print(f"[green]✅ Config loaded successfully[/]")
+        console.print(f"   VM Name: {vm_name}")
+        console.print(f"   RAM: {config['vm']['ram_mb']}MB")
+        console.print(f"   vCPUs: {config['vm']['vcpus']}")
+        console.print(f"   GUI: {'Yes' if config['vm']['gui'] else 'No'}")
+    except Exception as e:
+        console.print(f"[red]❌ Failed to load config: {e}[/]")
+        return
+    
+    console.print()
+    
+    # Test 1: Check VM exists
+    console.print("[bold]1. VM Existence Check[/]")
+    try:
+        result = subprocess.run(
+            ["virsh", "--connect", conn_uri, "dominfo", vm_name],
+            capture_output=True, text=True, timeout=10
+        )
+        if result.returncode == 0:
+            console.print("[green]✅ VM is defined in libvirt[/]")
+            if verbose:
+                for line in result.stdout.split('\n'):
+                    if ':' in line:
+                        console.print(f"   {line}")
+        else:
+            console.print("[red]❌ VM not found in libvirt[/]")
+            console.print("   Run: clonebox create .clonebox.yaml --start")
+            return
+    except Exception as e:
+        console.print(f"[red]❌ Error checking VM: {e}[/]")
+        return
+    
+    console.print()
+    
+    # Test 2: Check VM state
+    console.print("[bold]2. VM State Check[/]")
+    try:
+        result = subprocess.run(
+            ["virsh", "--connect", conn_uri, "domstate", vm_name],
+            capture_output=True, text=True, timeout=10
+        )
+        state = result.stdout.strip()
+        if state == "running":
+            console.print("[green]✅ VM is running[/]")
+            
+            # Test network if running
+            console.print("\n   Checking network...")
+            try:
+                result = subprocess.run(
+                    ["virsh", "--connect", conn_uri, "domifaddr", vm_name],
+                    capture_output=True, text=True, timeout=10
+                )
+                if "192.168" in result.stdout or "10.0" in result.stdout:
+                    console.print("[green]✅ VM has network access[/]")
+                    if verbose:
+                        for line in result.stdout.split('\n'):
+                            if '192.168' in line or '10.0' in line:
+                                console.print(f"   IP: {line.split()[-1]}")
+                else:
+                    console.print("[yellow]⚠️  No IP address detected[/]")
+            except:
+                console.print("[yellow]⚠️  Could not check network[/]")
+        else:
+            console.print(f"[yellow]⚠️  VM is not running (state: {state})[/]")
+            console.print("   Run: clonebox start .")
+    except Exception as e:
+        console.print(f"[red]❌ Error checking VM state: {e}[/]")
+    
+    console.print()
+    
+    # Test 3: Check cloud-init status (if running)
+    if not quick and state == "running":
+        console.print("[bold]3. Cloud-init Status[/]")
+        try:
+            # Try to get cloud-init status via QEMU guest agent
+            result = subprocess.run(
+                ["virsh", "--connect", conn_uri, "qemu-agent-command", vm_name,
+                 '{"execute":"guest-exec","arguments":{"path":"cloud-init","arg":["status"],"capture-output":true}}'],
+                capture_output=True, text=True, timeout=15
+            )
+            if result.returncode == 0:
+                try:
+                    response = json.loads(result.stdout)
+                    if "return" in response:
+                        pid = response["return"]["pid"]
+                        # Get output
+                        result2 = subprocess.run(
+                            ["virsh", "--connect", conn_uri, "qemu-agent-command", vm_name,
+                             f'{{"execute":"guest-exec-status","arguments":{"pid":{pid}}}}'],
+                            capture_output=True, text=True, timeout=15
+                        )
+                        if result2.returncode == 0:
+                            resp2 = json.loads(result2.stdout)
+                            if "return" in resp2 and resp2["return"]["exited"]:
+                                output = resp2["return"]["out-data"]
+                                if output:
+                                    import base64
+                                    status = base64.b64decode(output).decode()
+                                    if "done" in status.lower():
+                                        console.print("[green]✅ Cloud-init completed[/]")
+                                    elif "running" in status.lower():
+                                        console.print("[yellow]⚠️  Cloud-init still running[/]")
+                                    else:
+                                        console.print(f"[yellow]⚠️  Cloud-init status: {status.strip()}[/]")
+                except:
+                    pass
+        except:
+            console.print("[yellow]⚠️  Could not check cloud-init (QEMU agent may not be running)[/]")
+    
+    console.print()
+    
+    # Test 4: Check mounts (if running)
+    if not quick and state == "running":
+        console.print("[bold]4. Mount Points Check[/]")
+        all_paths = config.get("paths", {}).copy()
+        all_paths.update(config.get("app_data_paths", {}))
+        
+        if all_paths:
+            for idx, (host_path, guest_path) in enumerate(all_paths.items()):
+                try:
+                    result = subprocess.run(
+                        ["virsh", "--connect", conn_uri, "qemu-agent-command", vm_name,
+                         f'{{"execute":"guest-exec","arguments":{{"path":"test","arg":["-d","{guest_path}"],"capture-output":true}}}}'],
+                        capture_output=True, text=True, timeout=10
+                    )
+                    if result.returncode == 0:
+                        try:
+                            response = json.loads(result.stdout)
+                            if "return" in response:
+                                pid = response["return"]["pid"]
+                                result2 = subprocess.run(
+                                    ["virsh", "--connect", conn_uri, "qemu-agent-command", vm_name,
+                                     f'{{"execute":"guest-exec-status","arguments":{"pid":{pid}}}}'],
+                                    capture_output=True, text=True, timeout=10
+                                )
+                                if result2.returncode == 0:
+                                    resp2 = json.loads(result2.stdout)
+                                    if "return" in resp2 and resp2["return"]["exited"]:
+                                        exit_code = resp2["return"]["exitcode"]
+                                        if exit_code == 0:
+                                            console.print(f"[green]✅ {guest_path}[/]")
+                                        else:
+                                            console.print(f"[red]❌ {guest_path} (not accessible)[/]")
+                                        continue
+                        except:
+                            pass
+                    console.print(f"[yellow]⚠️  {guest_path} (unknown)[/]")
+                except:
+                    console.print(f"[yellow]⚠️  {guest_path} (could not check)[/]")
+        else:
+            console.print("[dim]No mount points configured[/]")
+    
+    console.print()
+    
+    # Test 5: Run health check (if running and not quick)
+    if not quick and state == "running":
+        console.print("[bold]5. Health Check[/]")
+        try:
+            result = subprocess.run(
+                ["virsh", "--connect", conn_uri, "qemu-agent-command", vm_name,
+                 '{"execute":"guest-exec","arguments":{"path":"/usr/local/bin/clonebox-health","capture-output":true}}'],
+                capture_output=True, text=True, timeout=60
+            )
+            if result.returncode == 0:
+                console.print("[green]✅ Health check triggered[/]")
+                console.print("   View results in VM: cat /var/log/clonebox-health.log")
+            else:
+                console.print("[yellow]⚠️  Health check script not found[/]")
+                console.print("   VM may not have been created with health checks")
+        except Exception as e:
+            console.print(f"[yellow]⚠️  Could not run health check: {e}[/]")
+    
+    console.print()
+    
+    # Summary
+    console.print("[bold]Test Summary[/]")
+    console.print("VM configuration is valid and VM is accessible.")
+    console.print("\n[dim]For detailed health report, run in VM:[/]")
+    console.print("[dim]  cat /var/log/clonebox-health.log[/]")
+
+
 CLONEBOX_CONFIG_FILE = ".clonebox.yaml"
 CLONEBOX_ENV_FILE = ".env"
 
@@ -1527,6 +1803,7 @@ def main():
         "name", nargs="?", default=None, help="VM name or '.' to use .clonebox.yaml"
     )
     start_parser.add_argument("--no-viewer", action="store_true", help="Don't open virt-viewer")
+    start_parser.add_argument("--viewer", action="store_true", help="Open virt-viewer GUI")
     start_parser.add_argument(
         "-u",
         "--user",
@@ -1535,6 +1812,19 @@ def main():
     )
     start_parser.set_defaults(func=cmd_start)
 
+    # Open command - open VM viewer
+    open_parser = subparsers.add_parser("open", help="Open VM viewer window")
+    open_parser.add_argument(
+        "name", nargs="?", default=None, help="VM name or '.' to use .clonebox.yaml"
+    )
+    open_parser.add_argument(
+        "-u",
+        "--user",
+        action="store_true",
+        help="Use user session (qemu:///session) - no root required",
+    )
+    open_parser.set_defaults(func=cmd_open)
+
     # Stop command
     stop_parser = subparsers.add_parser("stop", help="Stop a VM")
     stop_parser.add_argument("name", help="VM name")
@@ -1660,6 +1950,22 @@ def main():
     )
     import_parser.set_defaults(func=cmd_import)
 
+    # Test command - validate VM configuration
+    test_parser = subparsers.add_parser("test", help="Test VM configuration and health")
+    test_parser.add_argument(
+        "name", nargs="?", default=None, help="VM name or '.' to use .clonebox.yaml"
+    )
+    test_parser.add_argument(
+        "-u", "--user", action="store_true", help="Use user session (qemu:///session)"
+    )
+    test_parser.add_argument(
+        "--quick", action="store_true", help="Quick test (no deep health checks)"
+    )
+    test_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Verbose output"
+    )
+    test_parser.set_defaults(func=cmd_test)
+
     args = parser.parse_args()
 
     if hasattr(args, "func"):

clonebox/cloner.py

@@ -417,9 +417,10 @@ class SelectiveVMCloner:
             ET.SubElement(cdrom, "readonly")
 
         # 9p filesystem mounts (bind mounts from host)
+        # Use accessmode="mapped" to allow VM user to access host files regardless of UID
         for idx, (host_path, guest_tag) in enumerate(config.paths.items()):
             if Path(host_path).exists():
-                fs = ET.SubElement(devices, "filesystem", type="mount", accessmode="passthrough")
+                fs = ET.SubElement(devices, "filesystem", type="mount", accessmode="mapped")
                 ET.SubElement(fs, "driver", type="path", wrpolicy="immediate")
                 ET.SubElement(fs, "source", dir=host_path)
                 # Use simple tag names for 9p mounts

{clonebox-0.1.9.dist-info → clonebox-0.1.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clonebox
-Version: 0.1.9
+Version: 0.1.10
 Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
 Author: CloneBox Team
 License: Apache-2.0
@@ -64,6 +64,41 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 - 🖥️ **GUI support** - SPICE graphics with virt-viewer integration
 - ⚡ **Fast creation** - No full disk cloning, VMs are ready in seconds
 - 📥 **Auto-download** - Automatically downloads and caches Ubuntu cloud images (stored in ~/Downloads)
+- 📊 **Health monitoring** - Built-in health checks for packages, services, and mounts
+- 🔄 **VM migration** - Export/import VMs with data between workstations
+- 🧪 **Configuration testing** - Validate VM settings and functionality
+- 📁 **App data sync** - Include browser profiles, IDE settings, and app configs
+
+
+
+
+CloneBox to narzędzie CLI do **szybkiego klonowania aktualnego środowiska workstation do izolowanej maszyny wirtualnej (VM)**. 
+Zamiast pełnego kopiowania dysku, używa **bind mounts** (udostępnianie katalogów na żywo) i **cloud-init** do selektywnego przeniesienia tylko potrzebnych elementów: uruchomionych usług (Docker, PostgreSQL, nginx), aplikacji, ścieżek projektów i konfiguracji. Automatycznie pobiera obrazy Ubuntu, instaluje pakiety i uruchamia VM z SPICE GUI. Idealne dla deweloperów na Linuxie – VM powstaje w minuty, bez duplikowania danych.
+
+Kluczowe komendy:
+- `clonebox` – interaktywny wizard (detect + create + start)
+- `clonebox detect` – skanuje usługi/apps/ścieżki
+- `clonebox clone . --user --run` – szybki klon bieżącego katalogu z użytkownikiem i autostartem
+
+### Dlaczego wirtualne klony workstation mają sens?
+
+**Problem**: Developerzy/Vibecoderzy nie izolują środowisk dev/test (np. dla AI agentów), bo ręczne odtwarzanie setupu to ból – godziny na instalację apps, usług, configów, dotfiles. Przechodzenie z fizycznego PC na VM wymagałoby pełnego rebuilda, co blokuje workflow.
+
+**Rozwiązanie CloneBox**: Automatycznie **skanuje i klonuje stan "tu i teraz"** (usługi z `ps`, dockery z `docker ps`, projekty z git/.env). VM dziedziczy środowisko bez kopiowania całego śmietnika – tylko wybrane bind mounty. 
+
+**Korzyści w twoim kontekście (embedded/distributed systems, AI automation)**:
+- **Sandbox dla eksperymentów**: Testuj AI agenty, edge computing (RPi/ESP32 symulacje) czy Camel/ERP integracje w izolacji, bez psucia hosta.
+- **Reprodukcja workstation**: Na firmowym PC masz setup z domu (Python/Rust/Go envs, Docker compose, Postgres dev DB) – klonujesz i pracujesz identycznie.
+- **Szybkość > dotfiles**: Dotfiles odtwarzają configi, ale nie łapią runtime stanu (uruchomione serwery, otwarte projekty). CloneBox to "snapshot na sterydach".
+- **Bezpieczeństwo/cost-optymalizacja**: Izolacja od plików hosta (tylko mounts), zero downtime, tanie w zasobach (libvirt/QEMU). Dla SME: szybki onboarding dev env bez migracji fizycznej.
+- **AI-friendly**: Agenci LLMs (jak te z twoich hobby) mogą działać w VM z pełnym kontekstem, bez ryzyka "zasmiecania" main PC.
+
+Przykład: Masz uruchomiony Kubernetes Podman z twoim home labem + projekt automotive leasing. `clonebox clone ~/projects --run` → VM gotowa w 30s, z tymi samymi serwisami, ale izolowana. Lepsze niż Docker (brak GUI/full OS) czy pełna migracja.
+
+**Dlaczego ludzie tego nie robią?** Brak automatyzacji – nikt nie chce ręcznie rebuildować. 
+- CloneBox rozwiązuje to jednym poleceniem. Super match dla twoich interesów (distributed infra, AI tools, business automation).
+
+
 
 ## Installation
 
@@ -142,7 +177,6 @@ Simply run `clonebox` to start the interactive wizard:
 ```bash
 clonebox
 clonebox clone . --user --run --replace --base-image ~/ubuntu-22.04-cloud.qcow2
-
 ```
 
 The wizard will:
@@ -181,6 +215,130 @@ clonebox detect --json
 
 ## Usage Examples
 
+### Basic Workflow
+
+```bash
+# 1. Clone current directory with auto-detection
+clonebox clone . --user
+
+# 2. Review generated config
+cat .clonebox.yaml
+
+# 3. Create and start VM
+clonebox start . --user --viewer
+
+# 4. Check VM status
+clonebox status . --user
+
+# 5. Open VM window later
+clonebox open . --user
+
+# 6. Stop VM when done
+clonebox stop . --user
+```
+
+### Development Environment with Browser Profiles
+
+```bash
+# Clone with app data (browser profiles, IDE settings)
+clonebox clone . --user --run
+
+# VM will have:
+# - All your project directories
+# - Browser profiles (Chrome, Firefox) with bookmarks and passwords
+# - IDE settings (PyCharm, VSCode)
+# - Docker containers and services
+
+# Access in VM:
+ls ~/.config/google-chrome  # Chrome profile
+ls ~/.mozilla/firefox       # Firefox profile
+ls ~/.config/JetBrains      # PyCharm settings
+```
+
+### Testing VM Configuration
+
+```bash
+# Quick test - basic checks
+clonebox test . --user --quick
+
+# Full test with verbose output
+clonebox test . --user --verbose
+
+# Test output shows:
+# ✅ VM is defined in libvirt
+# ✅ VM is running
+# ✅ VM has network access (IP: 192.168.122.89)
+# ✅ Cloud-init completed
+# ✅ All mount points accessible
+# ✅ Health check triggered
+```
+
+### VM Health Monitoring
+
+```bash
+# Check overall status
+clonebox status . --user
+
+# Output:
+# 📊 Checking VM status: clone-clonebox
+# ✅ VM State: running
+# ✅ VM has network access
+# ☁️ Cloud-init: Still running (packages installing)
+# 🏥 Health Check Status... ⏳ Health check not yet run
+
+# Trigger health check
+clonebox status . --user --health
+
+# View detailed health report in VM:
+# cat /var/log/clonebox-health.log
+```
+
+### Export/Import Workflow
+
+```bash
+# On workstation A - Export VM with all data
+clonebox export . --user --include-data -o my-dev-env.tar.gz
+
+# Transfer file to workstation B, then import
+clonebox import my-dev-env.tar.gz --user
+
+# Start VM on new workstation
+clonebox start . --user
+clonebox open . --user
+
+# VM includes:
+# - Complete disk image
+# - All browser profiles and settings
+# - Project files
+# - Docker images and containers
+```
+
+### Troubleshooting Common Issues
+
+```bash
+# If mounts are empty after reboot:
+clonebox status . --user  # Check VM status
+# Then in VM:
+sudo mount -a              # Remount all fstab entries
+
+# If browser profiles don't sync:
+rm .clonebox.yaml
+clonebox clone . --user --run --replace
+
+# If GUI doesn't open:
+clonebox open . --user     # Easiest way
+# or:
+virt-viewer --connect qemu:///session clone-clonebox
+
+# Check VM details:
+clonebox list              # List all VMs
+virsh --connect qemu:///session dominfo clone-clonebox
+```
+
+## Legacy Examples (Manual Config)
+
+These examples use the older `create` command with manual JSON config. For most users, the `clone` command with auto-detection is easier.
+
 ### Python Development Environment
 
 ```bash
@@ -222,17 +380,36 @@ clonebox create --name fullstack --config '{
 
 ## Inside the VM
 
-After the VM boots, mount shared directories:
+After the VM boots, shared directories are automatically mounted via fstab entries. You can check their status:
 
 ```bash
-# Mount shared paths (9p filesystem)
-sudo mkdir -p /mnt/projects
-sudo mount -t 9p -o trans=virtio,version=9p2000.L mount0 /mnt/projects
+# Check mount status
+mount | grep 9p
 
-# Or add to /etc/fstab for permanent mount
-echo "mount0 /mnt/projects 9p trans=virtio,version=9p2000.L 0 0" | sudo tee -a /etc/fstab
+# View health check report
+cat /var/log/clonebox-health.log
+
+# Re-run health check manually
+clonebox-health
+
+# Check cloud-init status
+sudo cloud-init status
+
+# Manual mount (if needed)
+sudo mkdir -p /mnt/projects
+sudo mount -t 9p -o trans=virtio,version=9p2000.L,nofail mount0 /mnt/projects
 ```
 
+### Health Check System
+
+CloneBox includes automated health checks that verify:
+- Package installation (apt/snap)
+- Service status
+- Mount points accessibility
+- GUI readiness
+
+Health check logs are saved to `/var/log/clonebox-health.log` with a summary in `/var/log/clonebox-health-status`.
+
 ## Architecture
 
 ```
@@ -399,6 +576,7 @@ clonebox clone . --network auto
 | `clonebox clone . --network user` | Use user-mode networking (slirp) |
 | `clonebox clone . --network auto` | Auto-detect network mode (default) |
 | `clonebox start .` | Start VM from `.clonebox.yaml` in current dir |
+| `clonebox start . --viewer` | Start VM and open GUI window |
 | `clonebox start <name>` | Start existing VM by name |
 | `clonebox stop <name>` | Stop a VM (graceful shutdown) |
 | `clonebox stop -f <name>` | Force stop a VM |
@@ -408,6 +586,14 @@ clonebox clone . --network auto
 | `clonebox detect --yaml` | Output as YAML config |
 | `clonebox detect --yaml --dedupe` | YAML with duplicates removed |
 | `clonebox detect --json` | Output as JSON |
+| `clonebox status . --user` | Check VM health, cloud-init status, and IP address |
+| `clonebox test . --user` | Test VM configuration and validate all settings |
+| `clonebox export . --user` | Export VM for migration to another workstation |
+| `clonebox export . --user --include-data` | Export VM with browser profiles and configs |
+| `clonebox import archive.tar.gz --user` | Import VM from export archive |
+| `clonebox open . --user` | Open GUI viewer for VM (same as virt-viewer) |
+| `virt-viewer --connect qemu:///session <vm>` | Open GUI for running VM |
+| `virsh --connect qemu:///session console <vm>` | Open text console (Ctrl+] to exit) |
 
 ## Requirements
 
@@ -479,6 +665,102 @@ sudo apt install virt-viewer
 virt-viewer --connect qemu:///session <vm-name>
 ```
 
+### Browser Profiles Not Syncing
+
+If browser profiles or app data aren't available:
+
+1. **Regenerate config with app data:**
+   ```bash
+   rm .clonebox.yaml
+   clonebox clone . --user --run --replace
+   ```
+
+2. **Check mount permissions in VM:**
+   ```bash
+   # Verify mounts are accessible
+   ls -la ~/.config/google-chrome
+   ls -la ~/.mozilla/firefox
+   ```
+
+### Mount Points Empty After Reboot
+
+If shared directories appear empty after VM restart:
+
+1. **Check fstab entries:**
+   ```bash
+   cat /etc/fstab | grep 9p
+   ```
+
+2. **Mount manually:**
+   ```bash
+   sudo mount -a
+   ```
+
+3. **Verify access mode:**
+   - VMs created with `accessmode="mapped"` allow any user to access mounts
+   - Older VMs used `accessmode="passthrough"` which preserves host UIDs
+
+## Advanced Usage
+
+### VM Migration Between Workstations
+
+Export your complete VM environment:
+
+```bash
+# Export VM with all data
+clonebox export . --user --include-data -o my-dev-env.tar.gz
+
+# Transfer to new workstation, then import
+clonebox import my-dev-env.tar.gz --user
+clonebox start . --user
+```
+
+### Testing VM Configuration
+
+Validate your VM setup:
+
+```bash
+# Quick test (basic checks)
+clonebox test . --user --quick
+
+# Full test (includes health checks)
+clonebox test . --user --verbose
+```
+
+### Monitoring VM Health
+
+Check VM status from workstation:
+
+```bash
+# Check VM state, IP, cloud-init, and health
+clonebox status . --user
+
+# Trigger health check in VM
+clonebox status . --user --health
+```
+
+### Reopening VM Window
+
+If you close the VM window, you can reopen it:
+
+```bash
+# Open GUI viewer (easiest)
+clonebox open . --user
+
+# Start VM and open GUI (if VM is stopped)
+clonebox start . --user --viewer
+
+# Open GUI for running VM
+virt-viewer --connect qemu:///session clone-clonebox
+
+# List VMs to get the correct name
+clonebox list
+
+# Text console (no GUI)
+virsh --connect qemu:///session console clone-clonebox
+# Press Ctrl + ] to exit console
+```
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file.

clonebox-0.1.10.dist-info/RECORD

@@ -0,0 +1,11 @@
+clonebox/__init__.py,sha256=IOk7G0DiSQ33EGbFC0xbnnFB9aou_6yuyFxvycQEvA0,407
+clonebox/__main__.py,sha256=Fcoyzwwyz5-eC_sBlQk5a5RbKx8uodQz5sKJ190U0NU,135
+clonebox/cli.py,sha256=NFScoojeI1XJ982SuNt01iW52hHIYSttGy2UzZuJCCQ,76413
+clonebox/cloner.py,sha256=0puM04SzifccPfIVqc2CXFFcdNLWKpbiXXbBplrm9s8,31850
+clonebox/detector.py,sha256=4fu04Ty6KC82WkcJZ5UL5TqXpWYE7Kb7R0uJ-9dtbCk,21635
+clonebox-0.1.10.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+clonebox-0.1.10.dist-info/METADATA,sha256=hzdP5bntKA1s_RyRLx0hgbBzGrlt3NBGvDKu5YZfabE,24526
+clonebox-0.1.10.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+clonebox-0.1.10.dist-info/entry_points.txt,sha256=FES95Vi3btfViLEEoHdb8nikNxTqzaooi9ehZw9ZfWI,47
+clonebox-0.1.10.dist-info/top_level.txt,sha256=LdMo2cvCrEcRGH2M8JgQNVsCoszLV0xug6kx1JnaRjo,9
+clonebox-0.1.10.dist-info/RECORD,,

clonebox-0.1.9.dist-info/RECORD

@@ -1,11 +0,0 @@
-clonebox/__init__.py,sha256=IOk7G0DiSQ33EGbFC0xbnnFB9aou_6yuyFxvycQEvA0,407
-clonebox/__main__.py,sha256=Fcoyzwwyz5-eC_sBlQk5a5RbKx8uodQz5sKJ190U0NU,135
-clonebox/cli.py,sha256=BOAzIJCcRb52y_KgR7rU1yZiPt4r_Ws6Hk1hIPIH5bk,62714
-clonebox/cloner.py,sha256=Z9vpRu-imAWS-AwcPMG7jysvNhX7xn_Xk5Vze8y7DYE,31765
-clonebox/detector.py,sha256=4fu04Ty6KC82WkcJZ5UL5TqXpWYE7Kb7R0uJ-9dtbCk,21635
-clonebox-0.1.9.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-clonebox-0.1.9.dist-info/METADATA,sha256=A68kRx6uoFsNsEyH989LA1_9I1Oc6-saf3HzrAFtFd8,15582
-clonebox-0.1.9.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-clonebox-0.1.9.dist-info/entry_points.txt,sha256=FES95Vi3btfViLEEoHdb8nikNxTqzaooi9ehZw9ZfWI,47
-clonebox-0.1.9.dist-info/top_level.txt,sha256=LdMo2cvCrEcRGH2M8JgQNVsCoszLV0xug6kx1JnaRjo,9
-clonebox-0.1.9.dist-info/RECORD,,