clonebox 0.1.4__tar.gz → 0.1.6__tar.gz

{clonebox-0.1.4 → clonebox-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clonebox
-Version: 0.1.4
+Version: 0.1.6
 Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
 Author: CloneBox Team
 License: Apache-2.0
@@ -62,6 +62,7 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 - ☁️ **Cloud-init** - Automatic package installation and service setup
 - 🖥️ **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)
 
 ## Installation
 
@@ -139,6 +140,8 @@ 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:
@@ -259,6 +262,7 @@ The fastest way to clone your current working directory:
 
 ```bash
 # Clone current directory - generates .clonebox.yaml and asks to create VM
+# Base OS image is automatically downloaded to ~/Downloads on first run
 clonebox clone .
 
 # Clone specific path
@@ -269,6 +273,15 @@ clonebox clone ~/projects/my-app --name my-dev-vm --run
 
 # Clone and edit config before creating
 clonebox clone . --edit
+
+# Replace existing VM (stops, deletes, and recreates)
+clonebox clone . --replace
+
+# Use custom base image instead of auto-download
+clonebox clone . --base-image ~/ubuntu-22.04-cloud.qcow2
+
+# User session mode (no root required)
+clonebox clone . --user
 ```
 
 Later, start the VM from any directory with `.clonebox.yaml`:
@@ -291,6 +304,63 @@ clonebox detect --yaml --dedupe
 clonebox detect --yaml --dedupe -o my-config.yaml
 ```
 
+### Base Images
+
+CloneBox automatically downloads a bootable Ubuntu cloud image on first run:
+
+```bash
+# Auto-download (default) - downloads Ubuntu 22.04 to ~/Downloads on first run
+clonebox clone .
+
+# Use custom base image
+clonebox clone . --base-image ~/my-custom-image.qcow2
+
+# Manual download (optional - clonebox does this automatically)
+wget -O ~/Downloads/clonebox-ubuntu-jammy-amd64.qcow2 \
+  https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
+```
+
+**Base image behavior:**
+- If no `--base-image` is specified, Ubuntu 22.04 cloud image is auto-downloaded
+- Downloaded images are cached in `~/Downloads/clonebox-ubuntu-jammy-amd64.qcow2`
+- Subsequent VMs reuse the cached image (no re-download)
+- Each VM gets its own disk using the base image as a backing file (copy-on-write)
+
+### VM Login Credentials
+
+VM credentials are managed through `.env` file for security:
+
+**Setup:**
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` and set your password:
+   ```bash
+   # .env file
+   VM_PASSWORD=your_secure_password
+   VM_USERNAME=ubuntu
+   ```
+
+3. The `.clonebox.yaml` file references the password from `.env`:
+   ```yaml
+   vm:
+     username: ubuntu
+     password: ${VM_PASSWORD}  # Loaded from .env
+   ```
+
+**Default credentials (if .env not configured):**
+- **Username:** `ubuntu`
+- **Password:** `ubuntu`
+
+**Security notes:**
+- `.env` is automatically gitignored (never committed)
+- Username is stored in YAML (not sensitive)
+- Password is stored in `.env` (sensitive, not committed)
+- Change password after first login: `passwd`
+- User has passwordless sudo access
+
 ### User Session & Networking
 
 CloneBox supports creating VMs in user session (no root required) with automatic network fallback:
@@ -322,7 +392,9 @@ clonebox clone . --network auto
 | `clonebox clone <path>` | Generate `.clonebox.yaml` from path + running processes |
 | `clonebox clone . --run` | Clone and immediately start VM |
 | `clonebox clone . --edit` | Clone, edit config, then create |
+| `clonebox clone . --replace` | Replace existing VM (stop, delete, recreate) |
 | `clonebox clone . --user` | Clone in user session (no root) |
+| `clonebox clone . --base-image <path>` | Use custom base image |
 | `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 |
@@ -377,18 +449,21 @@ sudo usermod -aG kvm $USER
 
 ### VM Already Exists
 
-If you get "domain already exists" error:
+If you get "VM already exists" error:
 
 ```bash
-# List VMs
-clonebox list
+# Option 1: Use --replace flag to automatically replace it
+clonebox clone . --replace
 
-# Stop and delete the existing VM
+# Option 2: Delete manually first
 clonebox delete <vm-name>
 
-# Or use virsh directly
+# Option 3: Use virsh directly
 virsh --connect qemu:///session destroy <vm-name>
 virsh --connect qemu:///session undefine <vm-name>
+
+# Option 4: Start the existing VM instead
+clonebox start <vm-name>
 ```
 
 ### virt-viewer not found

{clonebox-0.1.4 → clonebox-0.1.6}/README.md

@@ -23,6 +23,7 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 - ☁️ **Cloud-init** - Automatic package installation and service setup
 - 🖥️ **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)
 
 ## Installation
 
@@ -100,6 +101,8 @@ 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:
@@ -220,6 +223,7 @@ The fastest way to clone your current working directory:
 
 ```bash
 # Clone current directory - generates .clonebox.yaml and asks to create VM
+# Base OS image is automatically downloaded to ~/Downloads on first run
 clonebox clone .
 
 # Clone specific path
@@ -230,6 +234,15 @@ clonebox clone ~/projects/my-app --name my-dev-vm --run
 
 # Clone and edit config before creating
 clonebox clone . --edit
+
+# Replace existing VM (stops, deletes, and recreates)
+clonebox clone . --replace
+
+# Use custom base image instead of auto-download
+clonebox clone . --base-image ~/ubuntu-22.04-cloud.qcow2
+
+# User session mode (no root required)
+clonebox clone . --user
 ```
 
 Later, start the VM from any directory with `.clonebox.yaml`:
@@ -252,6 +265,63 @@ clonebox detect --yaml --dedupe
 clonebox detect --yaml --dedupe -o my-config.yaml
 ```
 
+### Base Images
+
+CloneBox automatically downloads a bootable Ubuntu cloud image on first run:
+
+```bash
+# Auto-download (default) - downloads Ubuntu 22.04 to ~/Downloads on first run
+clonebox clone .
+
+# Use custom base image
+clonebox clone . --base-image ~/my-custom-image.qcow2
+
+# Manual download (optional - clonebox does this automatically)
+wget -O ~/Downloads/clonebox-ubuntu-jammy-amd64.qcow2 \
+  https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
+```
+
+**Base image behavior:**
+- If no `--base-image` is specified, Ubuntu 22.04 cloud image is auto-downloaded
+- Downloaded images are cached in `~/Downloads/clonebox-ubuntu-jammy-amd64.qcow2`
+- Subsequent VMs reuse the cached image (no re-download)
+- Each VM gets its own disk using the base image as a backing file (copy-on-write)
+
+### VM Login Credentials
+
+VM credentials are managed through `.env` file for security:
+
+**Setup:**
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` and set your password:
+   ```bash
+   # .env file
+   VM_PASSWORD=your_secure_password
+   VM_USERNAME=ubuntu
+   ```
+
+3. The `.clonebox.yaml` file references the password from `.env`:
+   ```yaml
+   vm:
+     username: ubuntu
+     password: ${VM_PASSWORD}  # Loaded from .env
+   ```
+
+**Default credentials (if .env not configured):**
+- **Username:** `ubuntu`
+- **Password:** `ubuntu`
+
+**Security notes:**
+- `.env` is automatically gitignored (never committed)
+- Username is stored in YAML (not sensitive)
+- Password is stored in `.env` (sensitive, not committed)
+- Change password after first login: `passwd`
+- User has passwordless sudo access
+
 ### User Session & Networking
 
 CloneBox supports creating VMs in user session (no root required) with automatic network fallback:
@@ -283,7 +353,9 @@ clonebox clone . --network auto
 | `clonebox clone <path>` | Generate `.clonebox.yaml` from path + running processes |
 | `clonebox clone . --run` | Clone and immediately start VM |
 | `clonebox clone . --edit` | Clone, edit config, then create |
+| `clonebox clone . --replace` | Replace existing VM (stop, delete, recreate) |
 | `clonebox clone . --user` | Clone in user session (no root) |
+| `clonebox clone . --base-image <path>` | Use custom base image |
 | `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 |
@@ -338,18 +410,21 @@ sudo usermod -aG kvm $USER
 
 ### VM Already Exists
 
-If you get "domain already exists" error:
+If you get "VM already exists" error:
 
 ```bash
-# List VMs
-clonebox list
+# Option 1: Use --replace flag to automatically replace it
+clonebox clone . --replace
 
-# Stop and delete the existing VM
+# Option 2: Delete manually first
 clonebox delete <vm-name>
 
-# Or use virsh directly
+# Option 3: Use virsh directly
 virsh --connect qemu:///session destroy <vm-name>
 virsh --connect qemu:///session undefine <vm-name>
+
+# Option 4: Start the existing VM instead
+clonebox start <vm-name>
 ```
 
 ### virt-viewer not found

{clonebox-0.1.4 → clonebox-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clonebox"
-version = "0.1.4"
+version = "0.1.6"
 description = "Clone your workstation environment to an isolated VM with selective apps, paths and services"
 readme = "README.md"
 license = {text = "Apache-2.0"}

{clonebox-0.1.4 → clonebox-0.1.6}/src/clonebox/cli.py

@@ -6,7 +6,9 @@ CloneBox CLI - Interactive command-line interface for creating VMs.
 import argparse
 import json
 import os
+import re
 import sys
+from typing import Optional
 from datetime import datetime
 from pathlib import Path
 
@@ -405,7 +407,7 @@ def cmd_start(args):
         vm_name = config["vm"]["name"]
 
         # Check if VM already exists
-        cloner = SelectiveVMCloner()
+        cloner = SelectiveVMCloner(user_session=getattr(args, "user", False))
         try:
             existing_vms = [v["name"] for v in cloner.list_vms()]
             if vm_name in existing_vms:
@@ -417,7 +419,7 @@ def cmd_start(args):
 
         # Create new VM from config
         console.print(f"[cyan]Creating VM '{vm_name}' from config...[/]\n")
-        vm_uuid = create_vm_from_config(config, start=True)
+        vm_uuid = create_vm_from_config(config, start=True, user_session=getattr(args, "user", False))
         console.print(f"\n[bold green]🎉 VM '{vm_name}' is running![/]")
         console.print(f"[dim]UUID: {vm_uuid}[/]")
 
@@ -442,13 +444,13 @@ def cmd_start(args):
             console.print("[dim]Usage: clonebox start <vm-name> or clonebox start .[/]")
             return
 
-    cloner = SelectiveVMCloner()
+    cloner = SelectiveVMCloner(user_session=getattr(args, "user", False))
     cloner.start_vm(name, open_viewer=not args.no_viewer, console=console)
 
 
 def cmd_stop(args):
     """Stop a VM."""
-    cloner = SelectiveVMCloner()
+    cloner = SelectiveVMCloner(user_session=getattr(args, "user", False))
     cloner.stop_vm(args.name, force=args.force, console=console)
 
 
@@ -461,13 +463,13 @@ def cmd_delete(args):
             console.print("[yellow]Cancelled.[/]")
             return
 
-    cloner = SelectiveVMCloner()
+    cloner = SelectiveVMCloner(user_session=getattr(args, "user", False))
     cloner.delete_vm(args.name, delete_storage=not args.keep_storage, console=console)
 
 
 def cmd_list(args):
     """List all VMs."""
-    cloner = SelectiveVMCloner()
+    cloner = SelectiveVMCloner(user_session=getattr(args, "user", False))
     vms = cloner.list_vms()
 
     if not vms:
@@ -487,6 +489,40 @@ def cmd_list(args):
 
 
 CLONEBOX_CONFIG_FILE = ".clonebox.yaml"
+CLONEBOX_ENV_FILE = ".env"
+
+
+def load_env_file(env_path: Path) -> dict:
+    """Load environment variables from .env file."""
+    env_vars = {}
+    if not env_path.exists():
+        return env_vars
+    
+    with open(env_path) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            if '=' in line:
+                key, value = line.split('=', 1)
+                env_vars[key.strip()] = value.strip()
+    
+    return env_vars
+
+
+def expand_env_vars(value, env_vars: dict):
+    """Expand environment variables in string values like ${VAR_NAME}."""
+    if isinstance(value, str):
+        # Replace ${VAR_NAME} with value from env_vars or os.environ
+        def replacer(match):
+            var_name = match.group(1)
+            return env_vars.get(var_name, os.environ.get(var_name, match.group(0)))
+        return re.sub(r'\$\{([^}]+)\}', replacer, value)
+    elif isinstance(value, dict):
+        return {k: expand_env_vars(v, env_vars) for k, v in value.items()}
+    elif isinstance(value, list):
+        return [expand_env_vars(item, env_vars) for item in value]
+    return value
 
 
 def deduplicate_list(items: list, key=None) -> list:
@@ -508,6 +544,7 @@ def generate_clonebox_yaml(
     target_path: str = None,
     vm_name: str = None,
     network_mode: str = "auto",
+    base_image: Optional[str] = None,
 ) -> str:
     """Generate YAML config from system snapshot."""
     sys_info = detector.get_system_info()
@@ -566,6 +603,23 @@ def generate_clonebox_yaml(
     ram_mb = min(4096, int(sys_info["memory_available_gb"] * 1024 * 0.5))
     vcpus = max(2, sys_info["cpu_count"] // 2)
 
+    # Auto-detect packages from running applications and services
+    suggested_app_packages = detector.suggest_packages_for_apps(snapshot.applications)
+    suggested_service_packages = detector.suggest_packages_for_services(snapshot.running_services)
+    
+    # Combine with base packages
+    base_packages = [
+        "build-essential",
+        "git",
+        "curl",
+        "vim",
+    ]
+    
+    # Merge all packages and deduplicate
+    all_packages = base_packages + suggested_app_packages + suggested_service_packages
+    if deduplicate:
+        all_packages = deduplicate_list(all_packages)
+
     # Build config
     config = {
         "version": "1",
@@ -575,18 +629,13 @@ def generate_clonebox_yaml(
             "ram_mb": ram_mb,
             "vcpus": vcpus,
             "gui": True,
-            "base_image": None,
+            "base_image": base_image,
             "network_mode": network_mode,
+            "username": "ubuntu",
+            "password": "${VM_PASSWORD}",
         },
         "services": services,
-        "packages": [
-            "build-essential",
-            "git",
-            "curl",
-            "vim",
-            "python3",
-            "python3-pip",
-        ],
+        "packages": all_packages,
         "paths": paths_mapping,
         "detected": {
             "running_apps": [
@@ -605,17 +654,115 @@ def generate_clonebox_yaml(
 
 
 def load_clonebox_config(path: Path) -> dict:
-    """Load .clonebox.yaml config file."""
+    """Load .clonebox.yaml config file and expand environment variables from .env."""
     config_file = path / CLONEBOX_CONFIG_FILE if path.is_dir() else path
 
     if not config_file.exists():
         raise FileNotFoundError(f"Config file not found: {config_file}")
 
-    with open(config_file) as f:
-        return yaml.safe_load(f)
-
+    # Load .env file from same directory
+    config_dir = config_file.parent
+    env_file = config_dir / CLONEBOX_ENV_FILE
+    env_vars = load_env_file(env_file)
 
-def create_vm_from_config(config: dict, start: bool = False, user_session: bool = False) -> str:
+    # Load YAML config
+    with open(config_file) as f:
+        config = yaml.safe_load(f)
+    
+    # Expand environment variables in config
+    config = expand_env_vars(config, env_vars)
+    
+    return config
+
+
+def monitor_cloud_init_status(vm_name: str, user_session: bool = False, timeout: int = 600):
+    """Monitor cloud-init status in VM and show progress."""
+    import subprocess
+    import time
+    
+    conn_uri = "qemu:///session" if user_session else "qemu:///system"
+    start_time = time.time()
+    shutdown_count = 0  # Count consecutive shutdown detections
+    restart_detected = False
+    
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("[cyan]Starting VM and initializing...", total=None)
+        
+        while time.time() - start_time < timeout:
+            try:
+                elapsed = int(time.time() - start_time)
+                minutes = elapsed // 60
+                seconds = elapsed % 60
+                
+                # Check VM state
+                result = subprocess.run(
+                    ["virsh", "--connect", conn_uri, "domstate", vm_name],
+                    capture_output=True,
+                    text=True,
+                    timeout=5
+                )
+                
+                vm_state = result.stdout.strip().lower()
+                
+                if "shut off" in vm_state or "shutting down" in vm_state:
+                    # VM is shutting down - count consecutive detections
+                    shutdown_count += 1
+                    if shutdown_count >= 3 and not restart_detected:
+                        # Confirmed shutdown after 3 consecutive checks
+                        restart_detected = True
+                        progress.update(task, description="[yellow]⟳ VM restarting after package installation...")
+                    time.sleep(3)
+                    continue
+                else:
+                    # VM is running - reset shutdown counter
+                    if shutdown_count > 0 and shutdown_count < 3:
+                        # Was a brief glitch, not a real shutdown
+                        shutdown_count = 0
+                
+                if restart_detected and "running" in vm_state and shutdown_count >= 3:
+                    # VM restarted successfully - GUI should be ready
+                    progress.update(task, description=f"[green]✓ GUI ready! Total time: {minutes}m {seconds}s")
+                    time.sleep(2)
+                    break
+                
+                # Estimate remaining time
+                if elapsed < 60:
+                    remaining = "~9-10 minutes"
+                elif elapsed < 180:
+                    remaining = f"~{8 - minutes} minutes"
+                elif elapsed < 300:
+                    remaining = f"~{6 - minutes} minutes"
+                else:
+                    remaining = "finishing soon"
+                
+                if restart_detected:
+                    progress.update(task, description=f"[cyan]Starting GUI... ({minutes}m {seconds}s, {remaining})")
+                else:
+                    progress.update(task, description=f"[cyan]Installing desktop packages... ({minutes}m {seconds}s, {remaining})")
+                
+            except (subprocess.TimeoutExpired, Exception) as e:
+                elapsed = int(time.time() - start_time)
+                minutes = elapsed // 60
+                seconds = elapsed % 60
+                progress.update(task, description=f"[cyan]Configuring VM... ({minutes}m {seconds}s)")
+            
+            time.sleep(3)
+        
+        # Final status
+        if time.time() - start_time >= timeout:
+            progress.update(task, description="[yellow]⚠ Monitoring timeout - VM continues in background")
+
+
+def create_vm_from_config(
+    config: dict,
+    start: bool = False,
+    user_session: bool = False,
+    replace: bool = False,
+) -> str:
     """Create VM from YAML config dict."""
     vm_config = VMConfig(
         name=config["vm"]["name"],
@@ -628,6 +775,8 @@ def create_vm_from_config(config: dict, start: bool = False, user_session: bool
         services=config.get("services", []),
         user_session=user_session,
         network_mode=config["vm"].get("network_mode", "auto"),
+        username=config["vm"].get("username", "ubuntu"),
+        password=config["vm"].get("password", "ubuntu"),
     )
 
     cloner = SelectiveVMCloner(user_session=user_session)
@@ -643,10 +792,20 @@ def create_vm_from_config(config: dict, start: bool = False, user_session: bool
 
     console.print(f"[dim]Session: {checks['session_type']}, Storage: {checks['images_dir']}[/]")
 
-    vm_uuid = cloner.create_vm(vm_config, console=console)
+    vm_uuid = cloner.create_vm(vm_config, console=console, replace=replace)
 
     if start:
         cloner.start_vm(vm_config.name, open_viewer=vm_config.gui, console=console)
+        
+        # Monitor cloud-init progress if GUI is enabled
+        if vm_config.gui:
+            console.print("\n[bold cyan]📊 Monitoring setup progress...[/]")
+            try:
+                monitor_cloud_init_status(vm_config.name, user_session=user_session)
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Monitoring stopped. VM continues setup in background.[/]")
+            except Exception as e:
+                console.print(f"\n[dim]Note: Could not monitor status ({e}). VM continues setup in background.[/]")
 
     return vm_uuid
 
@@ -681,6 +840,7 @@ def cmd_clone(args):
         target_path=str(target_path),
         vm_name=vm_name,
         network_mode=args.network,
+        base_image=getattr(args, "base_image", None),
     )
 
     # Save config file
@@ -712,7 +872,8 @@ def cmd_clone(args):
         ).ask()
 
     if create_now:
-        config = yaml.safe_load(yaml_content)
+        # Load config with environment variable expansion
+        config = load_clonebox_config(config_file.parent)
         user_session = getattr(args, "user", False)
 
         console.print("\n[bold cyan]🔧 Creating VM...[/]\n")
@@ -720,10 +881,26 @@ def cmd_clone(args):
             console.print("[cyan]Using user session (qemu:///session) - no root required[/]")
 
         try:
-            vm_uuid = create_vm_from_config(config, start=True, user_session=user_session)
+            vm_uuid = create_vm_from_config(
+                config,
+                start=True,
+                user_session=user_session,
+                replace=getattr(args, "replace", False),
+            )
             console.print(f"\n[bold green]🎉 VM '{config['vm']['name']}' is running![/]")
             console.print(f"[dim]UUID: {vm_uuid}[/]")
 
+            # Show GUI startup info if GUI is enabled
+            if config.get("vm", {}).get("gui", False):
+                username = config['vm'].get('username', 'ubuntu')
+                password = config['vm'].get('password', 'ubuntu')
+                console.print("\n[bold yellow]⏰ GUI Setup Process:[/]")
+                console.print("  [yellow]•[/] Installing desktop environment (~5-10 minutes)")
+                console.print("  [yellow]•[/] Automatic restart after installation")
+                console.print("  [yellow]•[/] GUI login screen will appear")
+                console.print(f"  [yellow]•[/] Login: [cyan]{username}[/] / [cyan]{'*' * len(password)}[/] (from .env)")
+                console.print("\n[dim]💡 Progress will be monitored automatically below[/]")
+
             # Show mount instructions
             if config.get("paths"):
                 console.print("\n[bold]Inside VM, mount paths with:[/]")
@@ -861,12 +1038,24 @@ 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(
+        "-u",
+        "--user",
+        action="store_true",
+        help="Use user session (qemu:///session) - no root required",
+    )
     start_parser.set_defaults(func=cmd_start)
 
     # Stop command
     stop_parser = subparsers.add_parser("stop", help="Stop a VM")
     stop_parser.add_argument("name", help="VM name")
     stop_parser.add_argument("--force", "-f", action="store_true", help="Force stop")
+    stop_parser.add_argument(
+        "-u",
+        "--user",
+        action="store_true",
+        help="Use user session (qemu:///session) - no root required",
+    )
     stop_parser.set_defaults(func=cmd_stop)
 
     # Delete command
@@ -874,10 +1063,22 @@ def main():
     delete_parser.add_argument("name", help="VM name")
     delete_parser.add_argument("--yes", "-y", action="store_true", help="Skip confirmation")
     delete_parser.add_argument("--keep-storage", action="store_true", help="Keep disk images")
+    delete_parser.add_argument(
+        "-u",
+        "--user",
+        action="store_true",
+        help="Use user session (qemu:///session) - no root required",
+    )
     delete_parser.set_defaults(func=cmd_delete)
 
     # List command
     list_parser = subparsers.add_parser("list", aliases=["ls"], help="List VMs")
+    list_parser.add_argument(
+        "-u",
+        "--user",
+        action="store_true",
+        help="Use user session (qemu:///session) - no root required",
+    )
     list_parser.set_defaults(func=cmd_list)
 
     # Detect command
@@ -915,6 +1116,15 @@ def main():
         default="auto",
         help="Network mode: auto (default), default (libvirt network), user (slirp)",
     )
+    clone_parser.add_argument(
+        "--base-image",
+        help="Path to a bootable qcow2 image to use as a base disk",
+    )
+    clone_parser.add_argument(
+        "--replace",
+        action="store_true",
+        help="If VM already exists, stop+undefine it and recreate (also deletes its storage)",
+    )
     clone_parser.set_defaults(func=cmd_clone)
 
     args = parser.parse_args()

{clonebox-0.1.4 → clonebox-0.1.6}/src/clonebox/cloner.py

@@ -5,6 +5,8 @@ SelectiveVMCloner - Creates isolated VMs with only selected apps/paths/services.
 
 import os
 import subprocess
+import tempfile
+import urllib.request
 import uuid
 import xml.etree.ElementTree as ET
 from dataclasses import dataclass, field
@@ -32,6 +34,8 @@ class VMConfig:
     services: list = field(default_factory=list)
     user_session: bool = False  # Use qemu:///session instead of qemu:///system
     network_mode: str = "auto"  # auto|default|user
+    username: str = "ubuntu"  # VM default username
+    password: str = "ubuntu"  # VM default password
 
     def to_dict(self) -> dict:
         return {
@@ -51,6 +55,11 @@ class SelectiveVMCloner:
     SYSTEM_IMAGES_DIR = Path("/var/lib/libvirt/images")
     USER_IMAGES_DIR = Path.home() / ".local/share/libvirt/images"
 
+    DEFAULT_BASE_IMAGE_URL = (
+        "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
+    )
+    DEFAULT_BASE_IMAGE_FILENAME = "clonebox-ubuntu-jammy-amd64.qcow2"
+
     def __init__(self, conn_uri: str = None, user_session: bool = False):
         self.user_session = user_session
         if conn_uri:
@@ -91,6 +100,57 @@ class SelectiveVMCloner:
             return self.USER_IMAGES_DIR
         return self.SYSTEM_IMAGES_DIR
 
+    def _get_downloads_dir(self) -> Path:
+        return Path.home() / "Downloads"
+
+    def _ensure_default_base_image(self, console=None) -> Path:
+        def log(msg):
+            if console:
+                console.print(msg)
+            else:
+                print(msg)
+
+        downloads_dir = self._get_downloads_dir()
+        downloads_dir.mkdir(parents=True, exist_ok=True)
+        cached_path = downloads_dir / self.DEFAULT_BASE_IMAGE_FILENAME
+
+        if cached_path.exists() and cached_path.stat().st_size > 0:
+            return cached_path
+
+        log(
+            "[cyan]⬇️  Downloading base image (first run only). This will be cached in ~/Downloads...[/]"
+        )
+
+        try:
+            with tempfile.NamedTemporaryFile(
+                prefix=f"{self.DEFAULT_BASE_IMAGE_FILENAME}.",
+                dir=str(downloads_dir),
+                delete=False,
+            ) as tmp:
+                tmp_path = Path(tmp.name)
+
+            try:
+                urllib.request.urlretrieve(self.DEFAULT_BASE_IMAGE_URL, tmp_path)
+                tmp_path.replace(cached_path)
+            finally:
+                if tmp_path.exists() and tmp_path != cached_path:
+                    try:
+                        tmp_path.unlink()
+                    except Exception:
+                        pass
+        except Exception as e:
+            raise RuntimeError(
+                "Failed to download a default base image.\n\n"
+                "🔧 Solutions:\n"
+                "  1. Provide a base image explicitly:\n"
+                "     clonebox clone . --base-image /path/to/image.qcow2\n"
+                "  2. Download it manually and reuse it:\n"
+                f"     wget -O {cached_path} {self.DEFAULT_BASE_IMAGE_URL}\n\n"
+                f"Original error: {e}"
+            ) from e
+
+        return cached_path
+
     def _default_network_active(self) -> bool:
         """Check if libvirt default network is active."""
         try:
@@ -175,7 +235,7 @@ class SelectiveVMCloner:
 
         return checks
 
-    def create_vm(self, config: VMConfig, console=None) -> str:
+    def create_vm(self, config: VMConfig, console=None, replace: bool = False) -> str:
         """
         Create a VM with only selected applications/paths.
 
@@ -193,6 +253,38 @@ class SelectiveVMCloner:
             else:
                 print(msg)
 
+        # If VM already exists, optionally replace it
+        existing_vm = None
+        try:
+            candidate_vm = self.conn.lookupByName(config.name)
+            if candidate_vm is not None:
+                # libvirt returns a domain object whose .name() should match the requested name.
+                # In tests, an unconfigured MagicMock may be returned here; avoid treating that as
+                # a real existing domain unless we can confirm the name matches.
+                try:
+                    if hasattr(candidate_vm, "name") and callable(candidate_vm.name):
+                        if candidate_vm.name() == config.name:
+                            existing_vm = candidate_vm
+                    else:
+                        existing_vm = candidate_vm
+                except Exception:
+                    existing_vm = candidate_vm
+        except Exception:
+            existing_vm = None
+
+        if existing_vm is not None:
+            if not replace:
+                raise RuntimeError(
+                    f"VM '{config.name}' already exists.\n\n"
+                    f"🔧 Solutions:\n"
+                    f"  1. Reuse existing VM: clonebox start {config.name}\n"
+                    f"  2. Replace it: clonebox clone . --name {config.name} --replace\n"
+                    f"  3. Delete it: clonebox delete {config.name}\n"
+                )
+
+            log(f"[yellow]⚠️  VM '{config.name}' already exists - replacing...[/]")
+            self.delete_vm(config.name, delete_storage=True, console=console, ignore_not_found=True)
+
         # Determine images directory
         images_dir = self.get_images_dir()
         vm_dir = images_dir / config.name
@@ -216,6 +308,9 @@ class SelectiveVMCloner:
         # Create root disk
         root_disk = vm_dir / "root.qcow2"
 
+        if not config.base_image:
+            config.base_image = str(self._ensure_default_base_image(console=console))
+
         if config.base_image and Path(config.base_image).exists():
             # Use backing file for faster creation
             log(f"[cyan]📀 Creating disk with backing file: {config.base_image}[/]")
@@ -258,7 +353,14 @@ class SelectiveVMCloner:
 
         # Define and create VM
         log(f"[cyan]🔧 Defining VM '{config.name}'...[/]")
-        vm = self.conn.defineXML(vm_xml)
+        try:
+            vm = self.conn.defineXML(vm_xml)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to define VM '{config.name}'.\n"
+                f"Error: {e}\n\n"
+                f"If the VM already exists, try: clonebox clone . --name {config.name} --replace\n"
+            ) from e
 
         log(f"[green]✅ VM '{config.name}' created successfully![/]")
         log(f"[dim]   UUID: {vm.UUIDString()}[/]")
@@ -393,27 +495,78 @@ class SelectiveVMCloner:
                 )
 
         # User-data
+        # Add desktop environment if GUI is enabled
+        base_packages = []
+        if config.gui:
+            base_packages.extend([
+                "ubuntu-desktop-minimal",
+                "firefox",
+            ])
+        
+        all_packages = base_packages + list(config.packages)
         packages_yaml = (
-            "\n".join(f"  - {pkg}" for pkg in config.packages) if config.packages else ""
+            "\n".join(f"  - {pkg}" for pkg in all_packages) if all_packages else ""
         )
-        services_enable = (
-            "\n".join(f"  - systemctl enable --now {svc}" for svc in config.services)
-            if config.services
-            else ""
-        )
-        mounts_yaml = "\n".join(mount_commands) if mount_commands else ""
+        
+        # Build runcmd - services and mounts
+        runcmd_lines = []
+        
+        # Add service enablement
+        for svc in config.services:
+            runcmd_lines.append(f"  - systemctl enable --now {svc} || true")
+        
+        # Add mounts
+        for cmd in mount_commands:
+            runcmd_lines.append(cmd)
+        
+        # Add GUI setup if enabled - runs AFTER package installation completes
+        if config.gui:
+            runcmd_lines.extend([
+                "  - systemctl set-default graphical.target",
+                "  - systemctl enable gdm3 || systemctl enable gdm || true",
+            ])
+        
+        runcmd_lines.append("  - echo 'CloneBox VM ready!' > /var/log/clonebox-ready")
+        
+        # Add reboot command at the end if GUI is enabled
+        if config.gui:
+            runcmd_lines.append("  - shutdown -r +1 'Rebooting to start GUI' || reboot")
+        
+        runcmd_yaml = "\n".join(runcmd_lines) if runcmd_lines else ""
+
+        # Remove power_state - using shutdown -r instead
+        power_state_yaml = ""
 
         user_data = f"""#cloud-config
 hostname: {config.name}
 manage_etc_hosts: true
 
+# Default user
+users:
+  - name: {config.username}
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    shell: /bin/bash
+    lock_passwd: false
+    groups: sudo,adm,dialout,cdrom,floppy,audio,dip,video,plugdev,netdev
+    plain_text_passwd: {config.password}
+
+# Allow password authentication
+ssh_pwauth: true
+chpasswd:
+  expire: false
+
+# Update package cache and upgrade
+package_update: true
+package_upgrade: false
+
+# Install packages (cloud-init waits for completion before runcmd)
 packages:
 {packages_yaml}
 
+# Run after packages are installed
 runcmd:
-{services_enable}
-{mounts_yaml}
-  - echo "CloneBox VM ready!" > /var/log/clonebox-ready
+{runcmd_yaml}
+{power_state_yaml}
 
 final_message: "CloneBox VM is ready after $UPTIME seconds"
 """
@@ -451,6 +604,8 @@ final_message: "CloneBox VM is ready after $UPTIME seconds"
         try:
             vm = self.conn.lookupByName(vm_name)
         except libvirt.libvirtError:
+            if ignore_not_found:
+                return False
             log(f"[red]❌ VM '{vm_name}' not found[/]")
             return False
 
@@ -500,7 +655,13 @@ final_message: "CloneBox VM is ready after $UPTIME seconds"
         log("[green]✅ VM stopped![/]")
         return True
 
-    def delete_vm(self, vm_name: str, delete_storage: bool = True, console=None) -> bool:
+    def delete_vm(
+        self,
+        vm_name: str,
+        delete_storage: bool = True,
+        console=None,
+        ignore_not_found: bool = False,
+    ) -> bool:
         """Delete a VM and optionally its storage."""
 
         def log(msg):
@@ -525,7 +686,7 @@ final_message: "CloneBox VM is ready after $UPTIME seconds"
 
         # Delete storage
         if delete_storage:
-            vm_dir = Path(f"/var/lib/libvirt/images/{vm_name}")
+            vm_dir = self.get_images_dir() / vm_name
             if vm_dir.exists():
                 import shutil
 

{clonebox-0.1.4 → clonebox-0.1.6}/src/clonebox/detector.py

@@ -146,6 +146,53 @@ class SystemDetector:
         "screen",
     ]
 
+    # Map process/service names to Ubuntu packages
+    APP_TO_PACKAGE_MAP = {
+        "python": "python3",
+        "python3": "python3",
+        "pip": "python3-pip",
+        "node": "nodejs",
+        "npm": "npm",
+        "yarn": "yarnpkg",
+        "docker": "docker.io",
+        "dockerd": "docker.io",
+        "docker-compose": "docker-compose",
+        "podman": "podman",
+        "nginx": "nginx",
+        "apache2": "apache2",
+        "httpd": "apache2",
+        "postgres": "postgresql",
+        "postgresql": "postgresql",
+        "mysql": "mysql-server",
+        "mysqld": "mysql-server",
+        "mongod": "mongodb",
+        "mongodb": "mongodb",
+        "redis-server": "redis-server",
+        "redis": "redis-server",
+        "vim": "vim",
+        "nvim": "neovim",
+        "emacs": "emacs",
+        "firefox": "firefox",
+        "chromium": "chromium-browser",
+        "jupyter": "jupyter-notebook",
+        "jupyter-lab": "jupyterlab",
+        "gunicorn": "gunicorn",
+        "uvicorn": "uvicorn",
+        "tmux": "tmux",
+        "screen": "screen",
+        "git": "git",
+        "curl": "curl",
+        "wget": "wget",
+        "ssh": "openssh-client",
+        "sshd": "openssh-server",
+        "go": "golang",
+        "cargo": "cargo",
+        "rustc": "rustc",
+        "java": "default-jdk",
+        "gradle": "gradle",
+        "mvn": "maven",
+    }
+
     def __init__(self):
         self.user = pwd.getpwuid(os.getuid()).pw_name
         self.home = Path.home()
@@ -390,6 +437,30 @@ class SystemDetector:
             pass
         return containers
 
+    def suggest_packages_for_apps(self, applications: list) -> list:
+        """Suggest Ubuntu packages based on detected applications."""
+        packages = set()
+        for app in applications:
+            app_name = app.name.lower()
+            # Check if app name matches any known mapping
+            for key, package in self.APP_TO_PACKAGE_MAP.items():
+                if key in app_name:
+                    packages.add(package)
+                    break
+        return sorted(list(packages))
+
+    def suggest_packages_for_services(self, services: list) -> list:
+        """Suggest Ubuntu packages based on detected services."""
+        packages = set()
+        for service in services:
+            service_name = service.name.lower()
+            # Check if service name matches any known mapping
+            for key, package in self.APP_TO_PACKAGE_MAP.items():
+                if key in service_name:
+                    packages.add(package)
+                    break
+        return sorted(list(packages))
+
     def get_system_info(self) -> dict:
         """Get basic system information."""
         return {

{clonebox-0.1.4 → clonebox-0.1.6}/src/clonebox.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clonebox
-Version: 0.1.4
+Version: 0.1.6
 Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
 Author: CloneBox Team
 License: Apache-2.0
@@ -62,6 +62,7 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 - ☁️ **Cloud-init** - Automatic package installation and service setup
 - 🖥️ **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)
 
 ## Installation
 
@@ -139,6 +140,8 @@ 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:
@@ -259,6 +262,7 @@ The fastest way to clone your current working directory:
 
 ```bash
 # Clone current directory - generates .clonebox.yaml and asks to create VM
+# Base OS image is automatically downloaded to ~/Downloads on first run
 clonebox clone .
 
 # Clone specific path
@@ -269,6 +273,15 @@ clonebox clone ~/projects/my-app --name my-dev-vm --run
 
 # Clone and edit config before creating
 clonebox clone . --edit
+
+# Replace existing VM (stops, deletes, and recreates)
+clonebox clone . --replace
+
+# Use custom base image instead of auto-download
+clonebox clone . --base-image ~/ubuntu-22.04-cloud.qcow2
+
+# User session mode (no root required)
+clonebox clone . --user
 ```
 
 Later, start the VM from any directory with `.clonebox.yaml`:
@@ -291,6 +304,63 @@ clonebox detect --yaml --dedupe
 clonebox detect --yaml --dedupe -o my-config.yaml
 ```
 
+### Base Images
+
+CloneBox automatically downloads a bootable Ubuntu cloud image on first run:
+
+```bash
+# Auto-download (default) - downloads Ubuntu 22.04 to ~/Downloads on first run
+clonebox clone .
+
+# Use custom base image
+clonebox clone . --base-image ~/my-custom-image.qcow2
+
+# Manual download (optional - clonebox does this automatically)
+wget -O ~/Downloads/clonebox-ubuntu-jammy-amd64.qcow2 \
+  https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
+```
+
+**Base image behavior:**
+- If no `--base-image` is specified, Ubuntu 22.04 cloud image is auto-downloaded
+- Downloaded images are cached in `~/Downloads/clonebox-ubuntu-jammy-amd64.qcow2`
+- Subsequent VMs reuse the cached image (no re-download)
+- Each VM gets its own disk using the base image as a backing file (copy-on-write)
+
+### VM Login Credentials
+
+VM credentials are managed through `.env` file for security:
+
+**Setup:**
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` and set your password:
+   ```bash
+   # .env file
+   VM_PASSWORD=your_secure_password
+   VM_USERNAME=ubuntu
+   ```
+
+3. The `.clonebox.yaml` file references the password from `.env`:
+   ```yaml
+   vm:
+     username: ubuntu
+     password: ${VM_PASSWORD}  # Loaded from .env
+   ```
+
+**Default credentials (if .env not configured):**
+- **Username:** `ubuntu`
+- **Password:** `ubuntu`
+
+**Security notes:**
+- `.env` is automatically gitignored (never committed)
+- Username is stored in YAML (not sensitive)
+- Password is stored in `.env` (sensitive, not committed)
+- Change password after first login: `passwd`
+- User has passwordless sudo access
+
 ### User Session & Networking
 
 CloneBox supports creating VMs in user session (no root required) with automatic network fallback:
@@ -322,7 +392,9 @@ clonebox clone . --network auto
 | `clonebox clone <path>` | Generate `.clonebox.yaml` from path + running processes |
 | `clonebox clone . --run` | Clone and immediately start VM |
 | `clonebox clone . --edit` | Clone, edit config, then create |
+| `clonebox clone . --replace` | Replace existing VM (stop, delete, recreate) |
 | `clonebox clone . --user` | Clone in user session (no root) |
+| `clonebox clone . --base-image <path>` | Use custom base image |
 | `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 |
@@ -377,18 +449,21 @@ sudo usermod -aG kvm $USER
 
 ### VM Already Exists
 
-If you get "domain already exists" error:
+If you get "VM already exists" error:
 
 ```bash
-# List VMs
-clonebox list
+# Option 1: Use --replace flag to automatically replace it
+clonebox clone . --replace
 
-# Stop and delete the existing VM
+# Option 2: Delete manually first
 clonebox delete <vm-name>
 
-# Or use virsh directly
+# Option 3: Use virsh directly
 virsh --connect qemu:///session destroy <vm-name>
 virsh --connect qemu:///session undefine <vm-name>
+
+# Option 4: Start the existing VM instead
+clonebox start <vm-name>
 ```
 
 ### virt-viewer not found

{clonebox-0.1.4 → clonebox-0.1.6}/tests/test_cli.py

@@ -151,6 +151,19 @@ class TestGenerateCloneboxYaml:
         assert "running_apps" in config["detected"]
         assert "all_paths" in config["detected"]
 
+    def test_generate_yaml_base_image(self):
+        snapshot = self.create_mock_snapshot()
+        detector = self.create_mock_detector()
+
+        yaml_str = generate_clonebox_yaml(
+            snapshot,
+            detector,
+            base_image="/images/base.qcow2",
+        )
+        config = yaml.safe_load(yaml_str)
+
+        assert config["vm"]["base_image"] == "/images/base.qcow2"
+
 
 class TestLoadCloneboxConfig:
     """Test loading .clonebox.yaml configs."""

{clonebox-0.1.4 → clonebox-0.1.6}/tests/test_cloner.py

@@ -241,6 +241,7 @@ class TestVMCreation:
     @patch("clonebox.cloner.libvirt")
     def test_create_vm_permission_error(self, mock_libvirt, mock_run):
         mock_conn = MagicMock()
+        mock_conn.lookupByName.side_effect = Exception("not found")
         mock_libvirt.open.return_value = mock_conn
 
         cloner = SelectiveVMCloner()