clonebox 0.1.2__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clonebox
-Version: 0.1.2
+Version: 0.1.4
 Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
 Author: CloneBox Team
 License: Apache-2.0
@@ -65,7 +65,28 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 
 ## Installation
 
-### Prerequisites
+### Quick Setup (Recommended)
+
+Run the setup script to automatically install dependencies and configure the environment:
+
+```bash
+# Clone the repository
+git clone https://github.com/wronai/clonebox.git
+cd clonebox
+
+# Run the setup script
+./setup.sh
+```
+
+The setup script will:
+- Install all required packages (QEMU, libvirt, Python, etc.)
+- Add your user to the necessary groups
+- Configure libvirt networks
+- Install clonebox in development mode
+
+### Manual Installation
+
+#### Prerequisites
 
 ```bash
 # Install libvirt and QEMU/KVM
@@ -82,7 +103,7 @@ newgrp libvirt
 sudo apt install genisoimage
 ```
 
-### Install CloneBox
+#### Install CloneBox
 
 ```bash
 # From source
@@ -270,6 +291,29 @@ clonebox detect --yaml --dedupe
 clonebox detect --yaml --dedupe -o my-config.yaml
 ```
 
+### User Session & Networking
+
+CloneBox supports creating VMs in user session (no root required) with automatic network fallback:
+
+```bash
+# Create VM in user session (uses ~/.local/share/libvirt/images)
+clonebox clone . --user
+
+# Explicitly use user-mode networking (slirp) - works without libvirt network
+clonebox clone . --user --network user
+
+# Force libvirt default network (may fail in user session)
+clonebox clone . --network default
+
+# Auto mode (default): tries libvirt network, falls back to user-mode if unavailable
+clonebox clone . --network auto
+```
+
+**Network modes:**
+- `auto` (default): Uses libvirt default network if available, otherwise falls back to user-mode (slirp)
+- `default`: Forces use of libvirt default network
+- `user`: Uses user-mode networking (slirp) - no bridge setup required
+
 ## Commands Reference
 
 | Command | Description |
@@ -278,6 +322,9 @@ clonebox detect --yaml --dedupe -o my-config.yaml
 | `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 . --user` | Clone in user session (no root) |
+| `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 <name>` | Start existing VM by name |
 | `clonebox stop <name>` | Stop a VM (graceful shutdown) |
@@ -296,6 +343,66 @@ clonebox detect --yaml --dedupe -o my-config.yaml
 - Python 3.8+
 - User in `libvirt` group
 
+## Troubleshooting
+
+### Network Issues
+
+If you encounter "Network not found" or "network 'default' is not active" errors:
+
+```bash
+# Option 1: Use user-mode networking (no setup required)
+clonebox clone . --user --network user
+
+# Option 2: Run the network fix script
+./fix-network.sh
+
+# Or manually fix:
+virsh --connect qemu:///session net-destroy default 2>/dev/null
+virsh --connect qemu:///session net-undefine default 2>/dev/null
+virsh --connect qemu:///session net-define /tmp/default-network.xml
+virsh --connect qemu:///session net-start default
+```
+
+### Permission Issues
+
+If you get permission errors:
+
+```bash
+# Ensure user is in libvirt and kvm groups
+sudo usermod -aG libvirt $USER
+sudo usermod -aG kvm $USER
+
+# Log out and log back in for groups to take effect
+```
+
+### VM Already Exists
+
+If you get "domain already exists" error:
+
+```bash
+# List VMs
+clonebox list
+
+# Stop and delete the existing VM
+clonebox delete <vm-name>
+
+# Or use virsh directly
+virsh --connect qemu:///session destroy <vm-name>
+virsh --connect qemu:///session undefine <vm-name>
+```
+
+### virt-viewer not found
+
+If GUI doesn't open:
+
+```bash
+# Install virt-viewer
+sudo apt install virt-viewer
+
+# Then connect manually
+virt-viewer --connect qemu:///session <vm-name>
+```
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file.

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

@@ -26,7 +26,28 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 
 ## Installation
 
-### Prerequisites
+### Quick Setup (Recommended)
+
+Run the setup script to automatically install dependencies and configure the environment:
+
+```bash
+# Clone the repository
+git clone https://github.com/wronai/clonebox.git
+cd clonebox
+
+# Run the setup script
+./setup.sh
+```
+
+The setup script will:
+- Install all required packages (QEMU, libvirt, Python, etc.)
+- Add your user to the necessary groups
+- Configure libvirt networks
+- Install clonebox in development mode
+
+### Manual Installation
+
+#### Prerequisites
 
 ```bash
 # Install libvirt and QEMU/KVM
@@ -43,7 +64,7 @@ newgrp libvirt
 sudo apt install genisoimage
 ```
 
-### Install CloneBox
+#### Install CloneBox
 
 ```bash
 # From source
@@ -231,6 +252,29 @@ clonebox detect --yaml --dedupe
 clonebox detect --yaml --dedupe -o my-config.yaml
 ```
 
+### User Session & Networking
+
+CloneBox supports creating VMs in user session (no root required) with automatic network fallback:
+
+```bash
+# Create VM in user session (uses ~/.local/share/libvirt/images)
+clonebox clone . --user
+
+# Explicitly use user-mode networking (slirp) - works without libvirt network
+clonebox clone . --user --network user
+
+# Force libvirt default network (may fail in user session)
+clonebox clone . --network default
+
+# Auto mode (default): tries libvirt network, falls back to user-mode if unavailable
+clonebox clone . --network auto
+```
+
+**Network modes:**
+- `auto` (default): Uses libvirt default network if available, otherwise falls back to user-mode (slirp)
+- `default`: Forces use of libvirt default network
+- `user`: Uses user-mode networking (slirp) - no bridge setup required
+
 ## Commands Reference
 
 | Command | Description |
@@ -239,6 +283,9 @@ clonebox detect --yaml --dedupe -o my-config.yaml
 | `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 . --user` | Clone in user session (no root) |
+| `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 <name>` | Start existing VM by name |
 | `clonebox stop <name>` | Stop a VM (graceful shutdown) |
@@ -257,6 +304,66 @@ clonebox detect --yaml --dedupe -o my-config.yaml
 - Python 3.8+
 - User in `libvirt` group
 
+## Troubleshooting
+
+### Network Issues
+
+If you encounter "Network not found" or "network 'default' is not active" errors:
+
+```bash
+# Option 1: Use user-mode networking (no setup required)
+clonebox clone . --user --network user
+
+# Option 2: Run the network fix script
+./fix-network.sh
+
+# Or manually fix:
+virsh --connect qemu:///session net-destroy default 2>/dev/null
+virsh --connect qemu:///session net-undefine default 2>/dev/null
+virsh --connect qemu:///session net-define /tmp/default-network.xml
+virsh --connect qemu:///session net-start default
+```
+
+### Permission Issues
+
+If you get permission errors:
+
+```bash
+# Ensure user is in libvirt and kvm groups
+sudo usermod -aG libvirt $USER
+sudo usermod -aG kvm $USER
+
+# Log out and log back in for groups to take effect
+```
+
+### VM Already Exists
+
+If you get "domain already exists" error:
+
+```bash
+# List VMs
+clonebox list
+
+# Stop and delete the existing VM
+clonebox delete <vm-name>
+
+# Or use virsh directly
+virsh --connect qemu:///session destroy <vm-name>
+virsh --connect qemu:///session undefine <vm-name>
+```
+
+### virt-viewer not found
+
+If GUI doesn't open:
+
+```bash
+# Install virt-viewer
+sudo apt install virt-viewer
+
+# Then connect manually
+virt-viewer --connect qemu:///session <vm-name>
+```
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clonebox"
-version = "0.1.2"
+version = "0.1.4"
 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/src/clonebox/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Entry point for python -m clonebox."""
+
+from clonebox.cli import main
+
+if __name__ == "__main__":
+    main()