clonebox 0.1.20__tar.gz → 0.1.22__tar.gz

{clonebox-0.1.20/src/clonebox.egg-info → clonebox-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clonebox
-Version: 0.1.20
+Version: 0.1.22
 Summary: Clone your workstation environment to an isolated VM with selective apps, paths and services
 Author: CloneBox Team
 License: Apache-2.0
@@ -85,6 +85,22 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 - 🧪 **Configuration testing** - Validate VM settings and functionality
 - 📁 **App data sync** - Include browser profiles, IDE settings, and app configs
 
+## Use Cases
+
+CloneBox excels in scenarios where developers need:
+- Isolated sandbox environments for testing AI agents, edge computing simulations, or integration workflows without risking host system stability
+- Reproducible development setups that can be quickly spun up with identical configurations across different machines
+- Safe experimentation with system-level changes that can be discarded by simply deleting the VM
+- Quick onboarding for new team members who need a fully configured development environment
+
+## What's Next
+
+Project roadmap includes:
+- Container runtime integration (Podman/Docker lightweight mode)
+- Local dashboard for VM and container management
+- Profile system for reusable configuration presets
+- Proxmox export capabilities for production migration
+
 
 
 
@@ -95,6 +111,8 @@ 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
+- `clonebox container up|ps|stop|rm` – lekki runtime kontenerowy (podman/docker)
+- `clonebox dashboard` – lokalny dashboard (VM + containers)
 
 ### Dlaczego wirtualne klony workstation mają sens?
 
@@ -167,6 +185,11 @@ pip install -e .
 # Or directly
 pip install clonebox
 ```
+
+Dashboard ma opcjonalne zależności:
+```bash
+pip install "clonebox[dashboard]"
+```
 lub
 ```bash
 # Aktywuj venv
@@ -247,7 +270,35 @@ Simply run `clonebox` to start the interactive wizard:
 
 ```bash
 clonebox
-clonebox clone . --user --run --replace --base-image ~/ubuntu-22.04-cloud.qcow2
+
+clonebox clone . --user --run --replace --base-image ~/ubuntu-22.04-cloud.qcow2 --disk-size-gb 30
+
+clonebox test . --user --validate
+clonebox test . --user --validate --require-running-apps
+```
+
+### Profiles (Reusable presets)
+
+Profiles pozwalają trzymać gotowe presety dla VM/container (np. `ml-dev`, `web-dev`) i nakładać je na bazową konfigurację.
+
+```bash
+# Przykład: uruchom kontener z profilem
+clonebox container up . --profile ml-dev --engine podman
+
+# Przykład: generuj VM config z profilem
+clonebox clone . --profile ml-dev --user --run
+```
+
+Domyślne lokalizacje profili:
+- `~/.clonebox.d/<name>.yaml`
+- `./.clonebox.d/<name>.yaml`
+- wbudowane: `src/clonebox/templates/profiles/<name>.yaml`
+
+### Dashboard
+
+```bash
+clonebox dashboard --port 8080
+# http://127.0.0.1:8080
 ```
 
 The wizard will:
@@ -268,7 +319,10 @@ clonebox create --name my-dev-vm --config '{
   },
   "packages": ["python3", "nodejs", "docker.io"],
   "services": ["docker"]
-}' --ram 4096 --vcpus 4 --start
+}' --ram 4096 --vcpus 4 --disk-size-gb 20 --start
+
+# Create VM with larger root disk
+clonebox create --name my-dev-vm --disk-size-gb 30 --config '{"paths": {}, "packages": [], "services": []}'
 
 # List VMs
 clonebox list
@@ -325,10 +379,45 @@ clonebox clone . --user --run
 
 # Access in VM:
 ls ~/.config/google-chrome  # Chrome profile
-ls ~/.mozilla/firefox       # Firefox profile
-ls ~/.config/JetBrains      # PyCharm settings
+
+# Firefox profile (Ubuntu często używa snap):
+ls ~/snap/firefox/common/.mozilla/firefox
+ls ~/.mozilla/firefox
+
+# PyCharm profile (snap):
+ls ~/snap/pycharm-community/common/.config/JetBrains
+ls ~/.config/JetBrains
+```
+
+### Container workflow (podman/docker)
+
+```bash
+# Start a dev container (auto-detect engine if not specified)
+clonebox container up . --engine podman --detach
+
+# List running containers
+clonebox container ps
+
+# Stop/remove
+clonebox container stop <name>
+clonebox container rm <name>
+```
+
+### Full validation (VM)
+
+`clonebox test` weryfikuje, że VM faktycznie ma zamontowane ścieżki i spełnia wymagania z `.clonebox.yaml`.
+
+```bash
+clonebox test . --user --validate
 ```
 
+Walidowane kategorie:
+- **Mounts** (9p)
+- **Packages** (apt)
+- **Snap packages**
+- **Services** (enabled + running)
+- **Apps** (instalacja + dostępność profilu: Firefox/PyCharm/Chrome)
+
 ### Testing and Validating VM Configuration
 
 ```bash
@@ -557,6 +646,9 @@ The fastest way to clone your current working directory:
 # Base OS image is automatically downloaded to ~/Downloads on first run
 clonebox clone .
 
+# Increase VM disk size (recommended for GUI + large tooling)
+clonebox clone . --user --disk-size-gb 30
+
 # Clone specific path
 clonebox clone ~/projects/my-app
 
@@ -687,8 +779,10 @@ clonebox clone . --network auto
 | `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 . --disk-size-gb <gb>` | Set root disk size in GB (generated configs default to 20GB) |
 | `clonebox clone . --network user` | Use user-mode networking (slirp) |
 | `clonebox clone . --network auto` | Auto-detect network mode (default) |
+| `clonebox create --config <json> --disk-size-gb <gb>` | Create VM from JSON config with specified disk size |
 | `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 |
@@ -701,6 +795,11 @@ 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 container up .` | Start a dev container for given path |
+| `clonebox container ps` | List containers |
+| `clonebox container stop <name>` | Stop a container |
+| `clonebox container rm <name>` | Remove a container |
+| `clonebox dashboard` | Run local dashboard (VM + containers) |
 | `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 (basic checks) |
@@ -721,6 +820,97 @@ clonebox clone . --network auto
 
 ## Troubleshooting
 
+### Critical: Insufficient Disk Space
+
+If you install a full desktop environment and large development tools (e.g. `ubuntu-desktop-minimal`, `docker.io`, large snaps like `pycharm-community`/`chromium`), you may hit low disk space warnings inside the VM.
+
+Recommended fix:
+- Set a larger root disk in `.clonebox.yaml`:
+
+```yaml
+vm:
+  disk_size_gb: 30
+```
+
+You can also set it during config generation:
+```bash
+clonebox clone . --user --disk-size-gb 30
+```
+
+Notes:
+- New configs generated by `clonebox clone` default to `disk_size_gb: 20`.
+- You can override this by setting `vm.disk_size_gb` in `.clonebox.yaml`.
+
+Workaround for an existing VM (host-side resize + guest filesystem grow):
+```bash
+clonebox stop . --user
+qemu-img resize ~/.local/share/libvirt/images/<vm-name>/root.qcow2 +10G
+clonebox start . --user
+```
+
+Inside the VM:
+```bash
+sudo growpart /dev/vda 1
+sudo resize2fs /dev/vda1
+df -h /
+```
+
+### Known Issue: IBus Preferences crash
+
+During validation you may occasionally see a crash dialog from **IBus Preferences** in the Ubuntu desktop environment.
+This is an upstream issue related to the input method daemon (`ibus-daemon`) and obsolete system packages (e.g. `libglib2.0`, `libssl3`, `libxml2`, `openssl`).
+It does **not** affect CloneBox functionality and the VM operates normally.
+
+Workaround:
+- Dismiss the crash dialog
+- Or run `sudo apt upgrade` inside the VM to update system packages
+
+### Snap Apps Not Launching (PyCharm, Chromium, Firefox)
+
+If snap-installed applications (e.g., PyCharm, Chromium) are installed but don't launch when clicked, the issue is usually **disconnected snap interfaces**. This happens because snap interfaces are not auto-connected when installing via cloud-init.
+
+**New VMs created with updated CloneBox automatically connect snap interfaces**, but for older VMs or manual installs:
+
+```bash
+# Check snap interface connections
+snap connections pycharm-community
+
+# If you see "-" instead of ":desktop", interfaces are NOT connected
+
+# Connect required interfaces
+sudo snap connect pycharm-community:desktop :desktop
+sudo snap connect pycharm-community:desktop-legacy :desktop-legacy
+sudo snap connect pycharm-community:x11 :x11
+sudo snap connect pycharm-community:wayland :wayland
+sudo snap connect pycharm-community:home :home
+sudo snap connect pycharm-community:network :network
+
+# Restart snap daemon and try again
+sudo systemctl restart snapd
+snap run pycharm-community
+```
+
+**For Chromium/Firefox:**
+```bash
+sudo snap connect chromium:desktop :desktop
+sudo snap connect chromium:x11 :x11
+sudo snap connect firefox:desktop :desktop
+sudo snap connect firefox:x11 :x11
+```
+
+**Debug launch:**
+```bash
+PYCHARM_DEBUG=true snap run pycharm-community 2>&1 | tee /tmp/pycharm-debug.log
+```
+
+**Nuclear option (reinstall):**
+```bash
+snap remove pycharm-community
+rm -rf ~/snap/pycharm-community
+sudo snap install pycharm-community --classic
+sudo snap connect pycharm-community:desktop :desktop
+```
+
 ### Network Issues
 
 If you encounter "Network not found" or "network 'default' is not active" errors:
@@ -1069,4 +1259,4 @@ qm set 9000 --boot c --bootdisk scsi0
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file.
+Apache License - see [LICENSE](LICENSE) file.

{clonebox-0.1.20 → clonebox-0.1.22}/README.md

@@ -37,6 +37,22 @@ CloneBox lets you create isolated virtual machines with only the applications, d
 - 🧪 **Configuration testing** - Validate VM settings and functionality
 - 📁 **App data sync** - Include browser profiles, IDE settings, and app configs
 
+## Use Cases
+
+CloneBox excels in scenarios where developers need:
+- Isolated sandbox environments for testing AI agents, edge computing simulations, or integration workflows without risking host system stability
+- Reproducible development setups that can be quickly spun up with identical configurations across different machines
+- Safe experimentation with system-level changes that can be discarded by simply deleting the VM
+- Quick onboarding for new team members who need a fully configured development environment
+
+## What's Next
+
+Project roadmap includes:
+- Container runtime integration (Podman/Docker lightweight mode)
+- Local dashboard for VM and container management
+- Profile system for reusable configuration presets
+- Proxmox export capabilities for production migration
+
 
 
 
@@ -47,6 +63,8 @@ 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
+- `clonebox container up|ps|stop|rm` – lekki runtime kontenerowy (podman/docker)
+- `clonebox dashboard` – lokalny dashboard (VM + containers)
 
 ### Dlaczego wirtualne klony workstation mają sens?
 
@@ -119,6 +137,11 @@ pip install -e .
 # Or directly
 pip install clonebox
 ```
+
+Dashboard ma opcjonalne zależności:
+```bash
+pip install "clonebox[dashboard]"
+```
 lub
 ```bash
 # Aktywuj venv
@@ -199,7 +222,35 @@ Simply run `clonebox` to start the interactive wizard:
 
 ```bash
 clonebox
-clonebox clone . --user --run --replace --base-image ~/ubuntu-22.04-cloud.qcow2
+
+clonebox clone . --user --run --replace --base-image ~/ubuntu-22.04-cloud.qcow2 --disk-size-gb 30
+
+clonebox test . --user --validate
+clonebox test . --user --validate --require-running-apps
+```
+
+### Profiles (Reusable presets)
+
+Profiles pozwalają trzymać gotowe presety dla VM/container (np. `ml-dev`, `web-dev`) i nakładać je na bazową konfigurację.
+
+```bash
+# Przykład: uruchom kontener z profilem
+clonebox container up . --profile ml-dev --engine podman
+
+# Przykład: generuj VM config z profilem
+clonebox clone . --profile ml-dev --user --run
+```
+
+Domyślne lokalizacje profili:
+- `~/.clonebox.d/<name>.yaml`
+- `./.clonebox.d/<name>.yaml`
+- wbudowane: `src/clonebox/templates/profiles/<name>.yaml`
+
+### Dashboard
+
+```bash
+clonebox dashboard --port 8080
+# http://127.0.0.1:8080
 ```
 
 The wizard will:
@@ -220,7 +271,10 @@ clonebox create --name my-dev-vm --config '{
   },
   "packages": ["python3", "nodejs", "docker.io"],
   "services": ["docker"]
-}' --ram 4096 --vcpus 4 --start
+}' --ram 4096 --vcpus 4 --disk-size-gb 20 --start
+
+# Create VM with larger root disk
+clonebox create --name my-dev-vm --disk-size-gb 30 --config '{"paths": {}, "packages": [], "services": []}'
 
 # List VMs
 clonebox list
@@ -277,10 +331,45 @@ clonebox clone . --user --run
 
 # Access in VM:
 ls ~/.config/google-chrome  # Chrome profile
-ls ~/.mozilla/firefox       # Firefox profile
-ls ~/.config/JetBrains      # PyCharm settings
+
+# Firefox profile (Ubuntu często używa snap):
+ls ~/snap/firefox/common/.mozilla/firefox
+ls ~/.mozilla/firefox
+
+# PyCharm profile (snap):
+ls ~/snap/pycharm-community/common/.config/JetBrains
+ls ~/.config/JetBrains
+```
+
+### Container workflow (podman/docker)
+
+```bash
+# Start a dev container (auto-detect engine if not specified)
+clonebox container up . --engine podman --detach
+
+# List running containers
+clonebox container ps
+
+# Stop/remove
+clonebox container stop <name>
+clonebox container rm <name>
+```
+
+### Full validation (VM)
+
+`clonebox test` weryfikuje, że VM faktycznie ma zamontowane ścieżki i spełnia wymagania z `.clonebox.yaml`.
+
+```bash
+clonebox test . --user --validate
 ```
 
+Walidowane kategorie:
+- **Mounts** (9p)
+- **Packages** (apt)
+- **Snap packages**
+- **Services** (enabled + running)
+- **Apps** (instalacja + dostępność profilu: Firefox/PyCharm/Chrome)
+
 ### Testing and Validating VM Configuration
 
 ```bash
@@ -509,6 +598,9 @@ The fastest way to clone your current working directory:
 # Base OS image is automatically downloaded to ~/Downloads on first run
 clonebox clone .
 
+# Increase VM disk size (recommended for GUI + large tooling)
+clonebox clone . --user --disk-size-gb 30
+
 # Clone specific path
 clonebox clone ~/projects/my-app
 
@@ -639,8 +731,10 @@ clonebox clone . --network auto
 | `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 . --disk-size-gb <gb>` | Set root disk size in GB (generated configs default to 20GB) |
 | `clonebox clone . --network user` | Use user-mode networking (slirp) |
 | `clonebox clone . --network auto` | Auto-detect network mode (default) |
+| `clonebox create --config <json> --disk-size-gb <gb>` | Create VM from JSON config with specified disk size |
 | `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 |
@@ -653,6 +747,11 @@ 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 container up .` | Start a dev container for given path |
+| `clonebox container ps` | List containers |
+| `clonebox container stop <name>` | Stop a container |
+| `clonebox container rm <name>` | Remove a container |
+| `clonebox dashboard` | Run local dashboard (VM + containers) |
 | `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 (basic checks) |
@@ -673,6 +772,97 @@ clonebox clone . --network auto
 
 ## Troubleshooting
 
+### Critical: Insufficient Disk Space
+
+If you install a full desktop environment and large development tools (e.g. `ubuntu-desktop-minimal`, `docker.io`, large snaps like `pycharm-community`/`chromium`), you may hit low disk space warnings inside the VM.
+
+Recommended fix:
+- Set a larger root disk in `.clonebox.yaml`:
+
+```yaml
+vm:
+  disk_size_gb: 30
+```
+
+You can also set it during config generation:
+```bash
+clonebox clone . --user --disk-size-gb 30
+```
+
+Notes:
+- New configs generated by `clonebox clone` default to `disk_size_gb: 20`.
+- You can override this by setting `vm.disk_size_gb` in `.clonebox.yaml`.
+
+Workaround for an existing VM (host-side resize + guest filesystem grow):
+```bash
+clonebox stop . --user
+qemu-img resize ~/.local/share/libvirt/images/<vm-name>/root.qcow2 +10G
+clonebox start . --user
+```
+
+Inside the VM:
+```bash
+sudo growpart /dev/vda 1
+sudo resize2fs /dev/vda1
+df -h /
+```
+
+### Known Issue: IBus Preferences crash
+
+During validation you may occasionally see a crash dialog from **IBus Preferences** in the Ubuntu desktop environment.
+This is an upstream issue related to the input method daemon (`ibus-daemon`) and obsolete system packages (e.g. `libglib2.0`, `libssl3`, `libxml2`, `openssl`).
+It does **not** affect CloneBox functionality and the VM operates normally.
+
+Workaround:
+- Dismiss the crash dialog
+- Or run `sudo apt upgrade` inside the VM to update system packages
+
+### Snap Apps Not Launching (PyCharm, Chromium, Firefox)
+
+If snap-installed applications (e.g., PyCharm, Chromium) are installed but don't launch when clicked, the issue is usually **disconnected snap interfaces**. This happens because snap interfaces are not auto-connected when installing via cloud-init.
+
+**New VMs created with updated CloneBox automatically connect snap interfaces**, but for older VMs or manual installs:
+
+```bash
+# Check snap interface connections
+snap connections pycharm-community
+
+# If you see "-" instead of ":desktop", interfaces are NOT connected
+
+# Connect required interfaces
+sudo snap connect pycharm-community:desktop :desktop
+sudo snap connect pycharm-community:desktop-legacy :desktop-legacy
+sudo snap connect pycharm-community:x11 :x11
+sudo snap connect pycharm-community:wayland :wayland
+sudo snap connect pycharm-community:home :home
+sudo snap connect pycharm-community:network :network
+
+# Restart snap daemon and try again
+sudo systemctl restart snapd
+snap run pycharm-community
+```
+
+**For Chromium/Firefox:**
+```bash
+sudo snap connect chromium:desktop :desktop
+sudo snap connect chromium:x11 :x11
+sudo snap connect firefox:desktop :desktop
+sudo snap connect firefox:x11 :x11
+```
+
+**Debug launch:**
+```bash
+PYCHARM_DEBUG=true snap run pycharm-community 2>&1 | tee /tmp/pycharm-debug.log
+```
+
+**Nuclear option (reinstall):**
+```bash
+snap remove pycharm-community
+rm -rf ~/snap/pycharm-community
+sudo snap install pycharm-community --classic
+sudo snap connect pycharm-community:desktop :desktop
+```
+
 ### Network Issues
 
 If you encounter "Network not found" or "network 'default' is not active" errors:
@@ -1021,4 +1211,4 @@ qm set 9000 --boot c --bootdisk scsi0
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file.
+Apache License - see [LICENSE](LICENSE) file.

{clonebox-0.1.20 → clonebox-0.1.22}/pyproject.toml

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