clonebox 0.1.14__tar.gz → 0.1.15__tar.gz

{clonebox-0.1.14 → clonebox-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clonebox
-Version: 0.1.14
+Version: 0.1.15
 Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
 Author: CloneBox Team
 License: Apache-2.0
@@ -30,14 +30,26 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.0.0; extra == "test"
 Dynamic: license-file
 
 # CloneBox 📦
+
+[![CI](https://github.com/wronai/clonebox/workflows/CI/badge.svg)](https://github.com/wronai/clonebox/actions)
+[![PyPI version](https://badge.fury.io/py/clonebox.svg)](https://pypi.org/project/clonebox/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
+
 ![img.png](img.png)
 
 ```commandline
@@ -51,7 +63,8 @@ Dynamic: license-file
 ║      Clone your workstation to an isolated VM         ║
 ╚═══════════════════════════════════════════════════════╝
 ```
-**Clone your workstation environment to an isolated VM with selective apps, paths and services.**
+
+> **Clone your workstation environment to an isolated VM in 60 seconds using bind mounts instead of disk cloning.**
 
 CloneBox lets you create isolated virtual machines with only the applications, directories and services you need - using bind mounts instead of full disk cloning. Perfect for development, testing, or creating reproducible environments.
 
@@ -168,6 +181,61 @@ clonebox stop <name>         # Zatrzymaj VM
 clonebox delete <name>       # Usuń VM
 ```
 
+## Development and Testing
+
+### Running Tests
+
+CloneBox has comprehensive test coverage with unit tests and end-to-end tests:
+
+```bash
+# Run unit tests only (fast, no libvirt required)
+make test
+
+# Run fast unit tests (excludes slow tests)
+make test-unit
+
+# Run end-to-end tests (requires libvirt/KVM)
+make test-e2e
+
+# Run all tests including e2e
+make test-all
+
+# Run tests with coverage
+make test-cov
+
+# Run tests with verbose output
+make test-verbose
+```
+
+### Test Categories
+
+Tests are organized with pytest markers:
+
+- **Unit tests**: Fast tests that mock libvirt/system calls (default)
+- **E2E tests**: End-to-end tests requiring actual VM creation (marked with `@pytest.mark.e2e`)
+- **Slow tests**: Tests that take longer to run (marked with `@pytest.mark.slow`)
+
+E2E tests are automatically skipped when:
+- libvirt is not installed
+- `/dev/kvm` is not available
+- Running in CI environment (`CI=true` or `GITHUB_ACTIONS=true`)
+
+### Manual Test Execution
+
+```bash
+# Run only unit tests (exclude e2e)
+pytest tests/ -m "not e2e"
+
+# Run only e2e tests
+pytest tests/e2e/ -m "e2e" -v
+
+# Run specific test file
+pytest tests/test_cloner.py -v
+
+# Run with coverage
+pytest tests/ -m "not e2e" --cov=clonebox --cov-report=html
+```
+
 ## Quick Start
 
 ### Interactive Mode (Recommended)
@@ -258,22 +326,53 @@ ls ~/.mozilla/firefox       # Firefox profile
 ls ~/.config/JetBrains      # PyCharm settings
 ```
 
-### Testing VM Configuration
+### Testing and Validating 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
+# Full validation - checks EVERYTHING against YAML config
+clonebox test . --user --validate
+
+# Validation checks:
+# ✅ All mount points (paths + app_data_paths) are mounted and accessible
+# ✅ All APT packages are installed
+# ✅ All snap packages are installed
+# ✅ All services are enabled and running
+# ✅ Reports file counts for each mount
+# ✅ Shows package versions
+# ✅ Comprehensive summary table
+
+# Example output:
+# 💾 Validating Mount Points...
+# ┌─────────────────────────┬─────────┬────────────┬────────┐
+# │ Guest Path              │ Mounted │ Accessible │ Files  │
+# ├─────────────────────────┼─────────┼────────────┼────────┤
+# │ /home/ubuntu/Downloads  │ ✅      │ ✅         │ 199    │
+# │ ~/.config/JetBrains     │ ✅      │ ✅         │ 45     │
+# └─────────────────────────┴─────────┴────────────┴────────┘
+# 12/14 mounts working
+#
+# 📦 Validating APT Packages...
+# ┌─────────────────┬──────────────┬────────────┐
+# │ Package         │ Status       │ Version    │
+# ├─────────────────┼──────────────┼────────────┤
+# │ firefox         │ ✅ Installed │ 122.0+b... │
+# │ docker.io       │ ✅ Installed │ 24.0.7-... │
+# └─────────────────┴──────────────┴────────────┘
+# 8/8 packages installed
+#
+# 📊 Validation Summary
+# ┌────────────────┬────────┬────────┬───────┐
+# │ Category       │ Passed │ Failed │ Total │
+# ├────────────────┼────────┼────────┼───────┤
+# │ Mounts         │ 12     │ 2      │ 14    │
+# │ APT Packages   │ 8      │ 0      │ 8     │
+# │ Snap Packages  │ 2      │ 0      │ 2     │
+# │ Services       │ 5      │ 1      │ 6     │
+# │ TOTAL          │ 27     │ 3      │ 30    │
+# └────────────────┴────────┴────────┴───────┘
 ```
 
 ### VM Health Monitoring and Mount Validation
@@ -601,7 +700,8 @@ clonebox clone . --network auto
 | `clonebox detect --json` | Output as JSON |
 | `clonebox status . --user` | Check VM health, cloud-init, IP, and mount status |
 | `clonebox status . --user --health` | Check VM status and run full health check |
-| `clonebox test . --user` | Test VM configuration and validate all settings |
+| `clonebox test . --user` | Test VM configuration (basic checks) |
+| `clonebox test . --user --validate` | Full validation: mounts, packages, services vs YAML |
 | `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-0.1.14/src/clonebox.egg-info/PKG-INFO → clonebox-0.1.15/README.md

@@ -1,43 +1,10 @@
-Metadata-Version: 2.4
-Name: clonebox
-Version: 0.1.14
-Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
-Author: CloneBox Team
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/wronai/clonebox
-Project-URL: Repository, https://github.com/wronai/clonebox
-Project-URL: Issues, https://github.com/wronai/clonebox/issues
-Keywords: vm,virtualization,libvirt,clone,workstation,qemu,kvm
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: System :: Systems Administration
-Classifier: Topic :: Utilities
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: libvirt-python>=9.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: questionary>=2.0.0
-Requires-Dist: psutil>=5.9.0
-Requires-Dist: pyyaml>=6.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
-Dynamic: license-file
-
 # CloneBox 📦
+
+[![CI](https://github.com/wronai/clonebox/workflows/CI/badge.svg)](https://github.com/wronai/clonebox/actions)
+[![PyPI version](https://badge.fury.io/py/clonebox.svg)](https://pypi.org/project/clonebox/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
+
 ![img.png](img.png)
 
 ```commandline
@@ -51,7 +18,8 @@ Dynamic: license-file
 ║      Clone your workstation to an isolated VM         ║
 ╚═══════════════════════════════════════════════════════╝
 ```
-**Clone your workstation environment to an isolated VM with selective apps, paths and services.**
+
+> **Clone your workstation environment to an isolated VM in 60 seconds using bind mounts instead of disk cloning.**
 
 CloneBox lets you create isolated virtual machines with only the applications, directories and services you need - using bind mounts instead of full disk cloning. Perfect for development, testing, or creating reproducible environments.
 
@@ -168,6 +136,61 @@ clonebox stop <name>         # Zatrzymaj VM
 clonebox delete <name>       # Usuń VM
 ```
 
+## Development and Testing
+
+### Running Tests
+
+CloneBox has comprehensive test coverage with unit tests and end-to-end tests:
+
+```bash
+# Run unit tests only (fast, no libvirt required)
+make test
+
+# Run fast unit tests (excludes slow tests)
+make test-unit
+
+# Run end-to-end tests (requires libvirt/KVM)
+make test-e2e
+
+# Run all tests including e2e
+make test-all
+
+# Run tests with coverage
+make test-cov
+
+# Run tests with verbose output
+make test-verbose
+```
+
+### Test Categories
+
+Tests are organized with pytest markers:
+
+- **Unit tests**: Fast tests that mock libvirt/system calls (default)
+- **E2E tests**: End-to-end tests requiring actual VM creation (marked with `@pytest.mark.e2e`)
+- **Slow tests**: Tests that take longer to run (marked with `@pytest.mark.slow`)
+
+E2E tests are automatically skipped when:
+- libvirt is not installed
+- `/dev/kvm` is not available
+- Running in CI environment (`CI=true` or `GITHUB_ACTIONS=true`)
+
+### Manual Test Execution
+
+```bash
+# Run only unit tests (exclude e2e)
+pytest tests/ -m "not e2e"
+
+# Run only e2e tests
+pytest tests/e2e/ -m "e2e" -v
+
+# Run specific test file
+pytest tests/test_cloner.py -v
+
+# Run with coverage
+pytest tests/ -m "not e2e" --cov=clonebox --cov-report=html
+```
+
 ## Quick Start
 
 ### Interactive Mode (Recommended)
@@ -258,22 +281,53 @@ ls ~/.mozilla/firefox       # Firefox profile
 ls ~/.config/JetBrains      # PyCharm settings
 ```
 
-### Testing VM Configuration
+### Testing and Validating 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
+# Full validation - checks EVERYTHING against YAML config
+clonebox test . --user --validate
+
+# Validation checks:
+# ✅ All mount points (paths + app_data_paths) are mounted and accessible
+# ✅ All APT packages are installed
+# ✅ All snap packages are installed
+# ✅ All services are enabled and running
+# ✅ Reports file counts for each mount
+# ✅ Shows package versions
+# ✅ Comprehensive summary table
+
+# Example output:
+# 💾 Validating Mount Points...
+# ┌─────────────────────────┬─────────┬────────────┬────────┐
+# │ Guest Path              │ Mounted │ Accessible │ Files  │
+# ├─────────────────────────┼─────────┼────────────┼────────┤
+# │ /home/ubuntu/Downloads  │ ✅      │ ✅         │ 199    │
+# │ ~/.config/JetBrains     │ ✅      │ ✅         │ 45     │
+# └─────────────────────────┴─────────┴────────────┴────────┘
+# 12/14 mounts working
+#
+# 📦 Validating APT Packages...
+# ┌─────────────────┬──────────────┬────────────┐
+# │ Package         │ Status       │ Version    │
+# ├─────────────────┼──────────────┼────────────┤
+# │ firefox         │ ✅ Installed │ 122.0+b... │
+# │ docker.io       │ ✅ Installed │ 24.0.7-... │
+# └─────────────────┴──────────────┴────────────┘
+# 8/8 packages installed
+#
+# 📊 Validation Summary
+# ┌────────────────┬────────┬────────┬───────┐
+# │ Category       │ Passed │ Failed │ Total │
+# ├────────────────┼────────┼────────┼───────┤
+# │ Mounts         │ 12     │ 2      │ 14    │
+# │ APT Packages   │ 8      │ 0      │ 8     │
+# │ Snap Packages  │ 2      │ 0      │ 2     │
+# │ Services       │ 5      │ 1      │ 6     │
+# │ TOTAL          │ 27     │ 3      │ 30    │
+# └────────────────┴────────┴────────┴───────┘
 ```
 
 ### VM Health Monitoring and Mount Validation
@@ -601,7 +655,8 @@ clonebox clone . --network auto
 | `clonebox detect --json` | Output as JSON |
 | `clonebox status . --user` | Check VM health, cloud-init, IP, and mount status |
 | `clonebox status . --user --health` | Check VM status and run full health check |
-| `clonebox test . --user` | Test VM configuration and validate all settings |
+| `clonebox test . --user` | Test VM configuration (basic checks) |
+| `clonebox test . --user --validate` | Full validation: mounts, packages, services vs YAML |
 | `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-0.1.14 → clonebox-0.1.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clonebox"
-version = "0.1.14"
+version = "0.1.15"
 description = "Clone your workstation environment to an isolated VM with selective apps, paths and services"
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -36,6 +36,7 @@ dependencies = [
     "questionary>=2.0.0",
     "psutil>=5.9.0",
     "pyyaml>=6.0",
+    "pydantic>=2.0.0",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +45,12 @@ dev = [
     "pytest-cov>=4.0.0",
     "black>=23.0.0",
     "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+test = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-timeout>=2.0.0",
 ]
 
 [project.scripts]
@@ -64,3 +71,31 @@ target-version = ["py38", "py39", "py310", "py311", "py312"]
 [tool.ruff]
 line-length = 100
 select = ["E", "F", "W", "I", "N", "UP", "B", "C4"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "e2e: end-to-end tests requiring libvirt/KVM (deselect with '-m \"not e2e\"')",
+    "slow: slow tests (deselect with '-m \"not slow\"')",
+    "integration: integration tests",
+    "requires_kvm: tests requiring /dev/kvm access",
+]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+    "--cov=src/clonebox",
+    "--cov-report=term-missing",
+    "--cov-fail-under=30",
+]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+    "ignore::UserWarning",
+]

{clonebox-0.1.14 → clonebox-0.1.15}/src/clonebox/cli.py

@@ -1347,11 +1347,24 @@ def cmd_test(args):
     
     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[/]")
+    # Run full validation if requested
+    if validate_all and state == "running":
+        validator = VMValidator(config, vm_name, conn_uri, console)
+        results = validator.validate_all()
+        
+        # Exit with error code if validations failed
+        if results["overall"] == "partial":
+            return 1
+    else:
+        # Summary
+        console.print("[bold]Test Summary[/]")
+        console.print("VM configuration is valid and VM is accessible.")
+        console.print("\n[dim]For full validation including packages, services, and mounts:[/]")
+        console.print("[dim]  clonebox test . --user --validate[/]")
+        console.print("\n[dim]For detailed health report, run in VM:[/]")
+        console.print("[dim]  cat /var/log/clonebox-health.log[/]")
+    
+    return 0
 
 
 CLONEBOX_CONFIG_FILE = ".clonebox.yaml"
@@ -1721,12 +1734,16 @@ def create_vm_from_config(
 def cmd_clone(args):
     """Generate clone config from path and optionally create VM."""
     target_path = Path(args.path).resolve()
+    dry_run = getattr(args, "dry_run", False)
 
     if not target_path.exists():
         console.print(f"[red]❌ Path does not exist: {target_path}[/]")
         return
 
-    console.print(f"[bold cyan]📦 Generating clone config for: {target_path}[/]\n")
+    if dry_run:
+        console.print(f"[bold cyan]🔍 DRY RUN - Analyzing: {target_path}[/]\n")
+    else:
+        console.print(f"[bold cyan]📦 Generating clone config for: {target_path}[/]\n")
 
     # Detect system state
     with Progress(
@@ -1751,6 +1768,25 @@ def cmd_clone(args):
         base_image=getattr(args, "base_image", None),
     )
 
+    # Dry run - show what would be created and exit
+    if dry_run:
+        config = yaml.safe_load(yaml_content)
+        console.print(Panel(
+            f"[bold]VM Name:[/] {config['vm']['name']}\n"
+            f"[bold]RAM:[/] {config['vm'].get('ram_mb', 4096)} MB\n"
+            f"[bold]vCPUs:[/] {config['vm'].get('vcpus', 4)}\n"
+            f"[bold]Network:[/] {config['vm'].get('network_mode', 'auto')}\n"
+            f"[bold]Paths:[/] {len(config.get('paths', {}))} mounts\n"
+            f"[bold]Packages:[/] {len(config.get('packages', []))} packages\n"
+            f"[bold]Services:[/] {len(config.get('services', []))} services",
+            title="[bold cyan]Would create VM[/]",
+            border_style="cyan",
+        ))
+        console.print("\n[dim]Config preview:[/]")
+        console.print(Panel(yaml_content, title="[bold].clonebox.yaml[/]", border_style="dim"))
+        console.print("\n[yellow]ℹ️  Dry run complete. No changes made.[/]")
+        return
+
     # Save config file
     config_file = (
         target_path / CLONEBOX_CONFIG_FILE
@@ -2058,6 +2094,11 @@ def main():
         action="store_true",
         help="If VM already exists, stop+undefine it and recreate (also deletes its storage)",
     )
+    clone_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be created without making any changes",
+    )
     clone_parser.set_defaults(func=cmd_clone)
 
     # Status command - check VM health from workstation
@@ -2118,6 +2159,9 @@ def main():
     test_parser.add_argument(
         "--verbose", "-v", action="store_true", help="Verbose output"
     )
+    test_parser.add_argument(
+        "--validate", action="store_true", help="Run full validation (mounts, packages, services)"
+    )
     test_parser.set_defaults(func=cmd_test)
 
     args = parser.parse_args()

clonebox-0.1.15/src/clonebox/models.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+Pydantic models for CloneBox configuration validation.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class VMSettings(BaseModel):
+    """VM-specific settings."""
+
+    name: str = Field(default="clonebox-vm", description="VM name")
+    ram_mb: int = Field(default=4096, ge=512, le=131072, description="RAM in MB")
+    vcpus: int = Field(default=4, ge=1, le=128, description="Number of vCPUs")
+    disk_size_gb: int = Field(default=10, ge=1, le=2048, description="Disk size in GB")
+    gui: bool = Field(default=True, description="Enable SPICE graphics")
+    base_image: Optional[str] = Field(default=None, description="Path to base qcow2 image")
+    network_mode: str = Field(default="auto", description="Network mode: auto|default|user")
+    username: str = Field(default="ubuntu", description="VM default username")
+    password: str = Field(default="ubuntu", description="VM default password")
+
+    @field_validator("name")
+    @classmethod
+    def name_must_be_valid(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("VM name cannot be empty")
+        if len(v) > 64:
+            raise ValueError("VM name must be <= 64 characters")
+        return v.strip()
+
+    @field_validator("network_mode")
+    @classmethod
+    def network_mode_must_be_valid(cls, v: str) -> str:
+        valid_modes = {"auto", "default", "user"}
+        if v not in valid_modes:
+            raise ValueError(f"network_mode must be one of: {valid_modes}")
+        return v
+
+
+class CloneBoxConfig(BaseModel):
+    """Complete CloneBox configuration with validation."""
+
+    version: str = Field(default="1", description="Config version")
+    generated: Optional[str] = Field(default=None, description="Generation timestamp")
+    vm: VMSettings = Field(default_factory=VMSettings, description="VM settings")
+    paths: Dict[str, str] = Field(default_factory=dict, description="Host:Guest path mappings")
+    app_data_paths: Dict[str, str] = Field(
+        default_factory=dict, description="Application data paths"
+    )
+    packages: List[str] = Field(default_factory=list, description="APT packages to install")
+    snap_packages: List[str] = Field(default_factory=list, description="Snap packages to install")
+    services: List[str] = Field(default_factory=list, description="Services to enable")
+    post_commands: List[str] = Field(default_factory=list, description="Post-setup commands")
+    detected: Optional[Dict[str, Any]] = Field(
+        default=None, description="Auto-detected system info"
+    )
+
+    @field_validator("paths", "app_data_paths")
+    @classmethod
+    def paths_must_be_absolute(cls, v: Dict[str, str]) -> Dict[str, str]:
+        for host_path, guest_path in v.items():
+            if not host_path.startswith("/"):
+                raise ValueError(f"Host path must be absolute: {host_path}")
+            if not guest_path.startswith("/"):
+                raise ValueError(f"Guest path must be absolute: {guest_path}")
+        return v
+
+    @model_validator(mode="before")
+    @classmethod
+    def handle_nested_vm(cls, data: Any) -> Any:
+        """Handle both dict and nested vm structures."""
+        if isinstance(data, dict):
+            if "vm" in data and isinstance(data["vm"], dict):
+                return data
+            vm_fields = {"name", "ram_mb", "vcpus", "disk_size_gb", "gui", "base_image", 
+                        "network_mode", "username", "password"}
+            vm_data = {k: v for k, v in data.items() if k in vm_fields}
+            if vm_data:
+                data = {k: v for k, v in data.items() if k not in vm_fields}
+                data["vm"] = vm_data
+        return data
+
+    def save(self, path: Path) -> None:
+        """Save configuration to YAML file."""
+        import yaml
+
+        config_dict = self.model_dump(exclude_none=True)
+        path.write_text(yaml.dump(config_dict, default_flow_style=False, sort_keys=False))
+
+    @classmethod
+    def load(cls, path: Path) -> "CloneBoxConfig":
+        """Load configuration from YAML file."""
+        import yaml
+
+        if path.is_dir():
+            path = path / ".clonebox.yaml"
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {path}")
+        data = yaml.safe_load(path.read_text())
+        return cls.model_validate(data)
+
+    def to_vm_config(self) -> "VMConfigDataclass":
+        """Convert to legacy VMConfig dataclass for compatibility."""
+        from clonebox.cloner import VMConfig as VMConfigDataclass
+
+        return VMConfigDataclass(
+            name=self.vm.name,
+            ram_mb=self.vm.ram_mb,
+            vcpus=self.vm.vcpus,
+            disk_size_gb=self.vm.disk_size_gb,
+            gui=self.vm.gui,
+            base_image=self.vm.base_image,
+            paths=self.paths,
+            packages=self.packages,
+            snap_packages=self.snap_packages,
+            services=self.services,
+            post_commands=self.post_commands,
+            network_mode=self.vm.network_mode,
+            username=self.vm.username,
+            password=self.vm.password,
+        )
+
+
+# Backwards compatibility alias
+VMConfigModel = CloneBoxConfig