navig-vm

Local VMware Workstation VMs from verified cloud images, provisioned on first boot with cloud-init and driven from navig vm (create, start, ssh, snapshots).

Works on its own — its own CLI, no navig required · v0.1.0 · not on PyPI yet (install from source below)

On its own (no navig needed)

pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-vm"
navig-vm --help   # no navig needed

With navig

pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-vm"
navig vm --help

Local virtual machines on VMware Workstation, built from a verified cloud image in one command and set up on first boot by cloud-init — then driven from the terminal.

navig vm create lab                      # Debian 13, 4 CPU, 8 GB, 40 GB, owner = your user name
navig vm create srv --image ubuntu-24.04 --headless   # Ubuntu Server 24.04 LTS instead
navig vm wait lab                        # until first-boot provisioning is done
navig vm ssh lab                         # a shell, with this VM's own SSH key
navig vm snapshot lab clean
navig vm revert lab clean                # back to it any time

Runs inside navig as navig vm, or on its own as navig-vm (pip install navig-vm).

A NAVIG OS lab machine

navig vm create navig-os-lab --recipe navig-os --repo <signed NAVIG apt repo folder> --keyboard fr
navig vm wait navig-os-lab
navig vm snapshot navig-os-lab fresh-install

The navig-os recipe shares the repository folder into the VM, installs the NAVIG OS packages from it with the same installer an existing Debian machine uses, and reboots into a login screen offering NAVIG OS (full screen) and GNOME (the desktop, with NAVIG OS as an app). Build the repository with apps/os/linux/build-all.sh.

How a VM is built

1. Downloads the cloud image once and checks it against the publisher's sums (Debian: SHA-512; Ubuntu: SHA-256).
2. Debian ships a raw disk: a VMDK descriptor points at it. Ubuntu ships a VMDK, used as-is. Either way vmware-vdiskmanager converts it to a growable disk and grows it to --disk GB (cloud-init grows the partition at boot). No third-party tool is needed.
3. Writes a cloud-init seed ISO (label CIDATA): the owner account (password stored only as a SHA-512 hash), a fresh SSH key for this VM, and the recipe.
4. Writes the .vmx — UEFI, PVSCSI, vmxnet3 on NAT.

Each VM is a folder under ~/Documents/Virtual Machines (change it with navig config set plugins.vm.dir <folder>) holding the VM, its own id_ed25519 and known_hosts, and navig-vm.json. Your personal SSH keys and known_hosts are never used or touched. destroy deletes only a folder navig created there.