delonix vm

microVMs declarativas: create, ls, stop, apply.

Declarative microVMs: create, ls, stop, apply.

MicroVMs geridas pelo trait VmBackend — Cloud Hypervisor ou libvirt. O create é idempotente (cria ou auto-recupera) e suporta cloud-init por instância: --hostname, --ssh-key e --user-data geram um ISO NoCloud automaticamente. É a camada que o delonix cluster kubeadm usa para provisionar nós.

MicroVMs managed by the VmBackend trait — Cloud Hypervisor or libvirt. create is idempotent (creates or self-heals) and supports per-instance cloud-init: --hostname, --ssh-key and --user-data generate a NoCloud ISO automatically. It's the layer delonix cluster kubeadm uses to provision nodes.

📄 Implementação real em Rust: cmd/vm.rs

Usage: delonix vm [OPTIONS] <COMMAND>

Commands:
  cloud-init       Change a STOPPED VM's cloud-init — hostname, user, SSH keys — for its next boot
  create           Create (or auto-recover) a VM
  destroy          Destroy VMs and everything they own — provider-side VM, disks, snapshots
  migrate          Move a VM to another `delonix` host — real downtime, no shared storage
  move             Move a VM to another node of its cluster — same VM, same record
  pause            Suspend a running VM's vCPUs — guest memory stays intact, unlike `stop`
  resize           Change a STOPPED VM's vCPUs and/or memory for its next boot
  restart          Stop (if running) then start — always a real reboot, unlike `start`. Same recovered-fields limits as `start`
  start            Start an existing, stopped VM — idempotent (already running = no-op)
  stop             Stop the VM (preserves disk, record and snapshots)
  unpause          Resume a VM suspended with `pause`. Refuses a VM that is not paused
  ls               List the VMs
  console          Attach to the VM's serial console (interactive terminal)
  ssh              SSH into a VM by NAME, or straight to an address
  vnc              Print the VNC address of a graphical VM (created with `--vnc`, libvirt)
  default-backend  Get or set the default VM backend
  bridge           EXPERIMENTAL (root): give a libvirt VM DIRECT IP reachability to a container SDN network
  reach            Which published ports a VM can actually reach, and how to fix the rest
  unbridge         Tear down a `vm bridge` (dry-run without `--apply`)
  build            Build a VM image (qcow2) from a `vm.yaml`, a `VMfile`, or the golden recipe
  convert          Convert a VM disk to the format another ecosystem imports
  ls-remote        List the tags available in a remote OCI repository
  pull             Pull a golden VM image from an OCI registry
  push             Push a local golden VM image to an OCI registry (`vm push <name> <target>`)
  apply            Apply the `kind: VirtualMachine` documents of a manifest
  init             Bootstrap a project with a VM manifest
  prune            Reclaim the VM state directory: everything in it no VM record accounts for
  snapshot         Point-in-time snapshots of a VM (checkpoints in the VM's own disk)
  help             Print this message or the help of the given subcommand(s)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

COMMAND MAP:
  Lifecycle    create · destroy · stop · start · restart · migrate · pause · unpause · cloud-init · resize · move
  Inspect      ls
  Interact     console · ssh · vnc
  Configure    default-backend
  Networking   reach · bridge · unbridge
  Storage      pull · ls-remote · push · convert · build
  Declarative  init · apply
  Maintenance  prune · snapshot

EXAMPLES:
  # the official golden image, ready to boot without installing anything
  delonix vm pull

  # a VM from it, waiting until it has a real IP
  delonix vm create dev --vcpus 2 --memory 4G --wait

  # what is up, and the address each one got
  delonix vm ls

  # the boot log and a login, with no IP and no SSH yet
  delonix vm console dev

SEE ALSO:
  delonix image vm ls · delonix cluster kubeadm · delonix workload ls ·
  delonix container run

  delonix › vm

ExemplosExamples

Detalhe de uma VM, reconciliando liveness/IP com o backend — `vm status` saiu na v3.0.0

Detail of one VM, reconciling liveness/IP with the backend — `vm status` went away in v3.0.0

delonix describe vm node1

Remover a VM

Remove the VM

delonix delete vm node1

`vm ssh`

SSH into a VM by NAME, or straight to an address.

The name is enough — its IP comes from the record. With a trailing command, runs it and returns instead of opening a shell.

delonix vm ssh dev · delonix vm ssh dev -- systemctl status · delonix vm ssh 192.168.122.50 -l root

Usage: delonix vm ssh [OPTIONS] <TARGET> [COMMAND]...

Arguments:
  <TARGET>
          VM name (`vm ls`) or an IP/hostname to go to directly

  [COMMAND]...
          Command to run instead of an interactive shell

Options:
  -l, --user <USER>
          Login user. Default: `delonix` on cloud-init images, `root` on appliances (which have no `delonix` account)

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -i, --identity <IDENTITY>
          Private key to authenticate with (`ssh -i`)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # a shell inside the VM — the IP comes from the record, so the name is
  # enough
  delonix vm ssh dev

  # one command and out, instead of an interactive shell
  delonix vm ssh dev -- systemctl status kubelet

  # straight to an address, as another user
  delonix vm ssh 192.168.122.50 -l root

SEE ALSO:
  delonix vm console · delonix vm ls · delonix vm create

  delonix › vm › ssh

ExemplosExamples

Entrar numa VM pelo NOME — o IP vem do registo, e o utilizador por omissão é `delonix` (não o da distro, que existe e não tem a chave)

Enter a VM by NAME — the IP comes from the record, and the default user is `delonix` (not the distro's own, which exists and does not carry the key)

delonix vm ssh dev

Correr um comando e voltar, em vez de abrir uma shell

Run a command and return, instead of opening a shell

delonix vm ssh dev -- systemctl is-system-running

Ir directamente a um endereço, com outro utilizador e outra chave

Go straight to an address, with a different user and key

delonix vm ssh 192.168.122.50 -l root -i ~/.ssh/id_ed25519

`vm convert`

Convert a VM disk to the format another ecosystem imports.

qcow2, raw, vmdk (VMware), vdi (VirtualBox), vhdx/vhd (Hyper-V, Azure). Flattened either way, so the result is a standalone file with no backing chain. This engine's own two backends already share qcow2/raw; the rest exist so an image built here is importable elsewhere without a backend per product.

Usage: delonix vm convert [OPTIONS] --to <TO> <SOURCE>

Arguments:
  <SOURCE>
          A local VM image name (`vm ls`) or a literal `.qcow2`/`.raw` path

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --to <TO>
          Possible values:
          - qcow2: QEMU/KVM, libvirt, Cloud Hypervisor — this engine's own two backends
          - raw:   Raw sectors: Proxmox VE (its default for LVM/ZFS/Ceph storage), and the universal fallback anything can read. Not sparse on a filesystem that does not support holes — expect the full virtual size on disk
          - vmdk:  VMware — Workstation, Fusion, ESXi/vSphere
          - vdi:   VirtualBox
          - vhdx:  Hyper-V (Windows 8/2012 and later), and Azure's modern disk format
          - vhd:   Hyper-V's older VHD (`vpc` in qemu-img's own naming). Kept separate from `vhdx` because they are different formats, not spellings — an importer that wants one rejects the other

  -o, --output <OUTPUT>
          Destination file (default: alongside the source, with the new extension)

      --compress
          Compress the output. Only `qcow2` and `vmdk` can — refused for the others rather than handed to `qemu-img` to fail on

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # hand an image built here to VMware, flattened so there is no backing chain
  # to carry with it
  delonix vm convert lab:1.0 --to vmdk

  # raw for Proxmox VE's LVM/ZFS/Ceph storage, written where you want it
  delonix vm convert lab:1.0 --to raw -o /srv/lab.raw

  # back to qcow2 and compressed — only qcow2 and vmdk can, the rest are
  # refused up front
  delonix vm convert /srv/lab.raw --to qcow2 --compress

  # Hyper-V and Azure take vhdx; the older vhd is a different format, not
  # another spelling
  delonix vm convert lab:1.0 --to vhdx

SEE ALSO:
  delonix image vm build · delonix image vm ls · delonix vm push · delonix vm
  create

  delonix › vm › convert

ExemplosExamples

Levar uma imagem construída aqui para outro ecossistema

delonix vm convert minha-base --to vmdk        # VMware
delonix vm convert minha-base --to vdi         # VirtualBox
delonix vm convert minha-base --to vhdx        # Hyper-V / Azure

Comprimir — só `qcow2` e `vmdk` o sabem fazer; nos outros é recusado com a lista, em vez de entregue ao qemu-img para falhar lá

delonix vm convert minha-base --to qcow2 --compress

`vm default-backend`

Get or set the default VM backend.

Used by vm create when neither --backend nor DELONIX_VM_BACKEND is given. It lives in the node's providers file (defaultProvider, ADR-0054): --set edits that line and nothing else in the file. With no flag, prints the current default (none if auto-detection decides).

Usage: delonix vm default-backend [OPTIONS]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --set <SET>
          Set `defaultProvider` in the providers file (`libvirt`, `cloud-hypervisor`, or a configured `proxmox`)

      --clear
          Remove `defaultProvider` from the providers file

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # which backend `vm create` will pick when nothing on the command line says
  # otherwise
  delonix vm default-backend

  # pin libvirt once, instead of passing `--backend` on every create — it is
  # the backend with snapshots and a NAT address
  delonix vm default-backend --set libvirt

  # hand the choice back to auto-detection
  delonix vm default-backend --clear

SEE ALSO:
  delonix vm create · delonix vm snapshot · delonix vm ls

  delonix › vm › default-backend

ExemplosExamples

Fixar o backend que o `vm create` usa quando não lhe dizem nada

delonix vm default-backend --set libvirt

Ver o que está fixado (`none` = decide a auto-detecção)

delonix vm default-backend

Voltar à auto-detecção

delonix vm default-backend --clear

`vm snapshot`

Point-in-time snapshots of a VM (checkpoints in the VM's own disk).

libvirt: a snapshot of a RUNNING VM is a system checkpoint — memory + disk — and of a stopped one it is disk-only; either survives a vm stop/vm start. cloud-hypervisor: stopped VMs only, because the running vmm holds the disk exclusively and CH has no live disk-snapshot API — it says so instead of writing nothing.

Usage: delonix vm snapshot [OPTIONS] <COMMAND>

Commands:
  create   Take a named snapshot (memory + disk if the VM is running, disk-only if it is stopped)
  restore  Revert the VM to a named snapshot
  rm       Delete a snapshot (its state in the disk goes with it)
  ls       List the VM's snapshots
  help     Print this message or the help of the given subcommand(s)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

COMMAND MAP:
  Lifecycle  create · rm · restore
  Inspect    ls

EXAMPLES:
  # a checkpoint before an upgrade — of a RUNNING VM it takes the memory too
  delonix vm snapshot create dev before-upgrade

  # which checkpoints a VM has, before reverting to one
  delonix vm snapshot ls dev

SEE ALSO:
  delonix vm stop · delonix get · delonix volume snapshot · delonix vm
  default-backend

  delonix › vm › snapshot

ExemplosExamples

Checkpoint de sistema (memória + disco) de uma VM A CORRER

System checkpoint (memory + disk) of a RUNNING VM

delonix vm snapshot create dev antes-do-upgrade

Com a VM parada é só do disco — e a VM continua parada

Of a stopped one it is disk-only — and it stays stopped

delonix vm snapshot create dev copia-fria

Listar os checkpoints de uma VM (também com ela parada)

List a VM's checkpoints (with the VM stopped too)

delonix vm snapshot ls dev

Voltar ao checkpoint

Roll back to the checkpoint

delonix vm snapshot restore dev antes-do-upgrade

Apagar um checkpoint (o estado dele sai do disco)

Delete a checkpoint (its state leaves the disk)

delonix vm snapshot rm dev antes-do-upgrade

`vm restart`

Stop (if running) then start — always a real reboot, unlike start. Same recovered-fields limits as start

Usage: delonix vm restart [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # a real reboot — `start` on an already-running VM does nothing, this one
  # always cycles it
  delonix vm restart dev

SEE ALSO:
  delonix vm start · delonix vm stop · delonix vm console · delonix get

  delonix › vm › restart

ExemplosExamples

Reinício forçado (pára e volta a arrancar)

Forced restart (stops and boots again)

delonix vm restart dev

`vm start`

Start an existing, stopped VM — idempotent (already running = no-op).

Reboots with everything recorded at its last create/start — base disk/vcpus/memory/network/backend AND the boot shape (custom kernel/seed/volumes/static IP/VNC/TPM/CPU topology/extra disks and NICs/advanced libvirt knobs) — reusing the same overlay, so disk state is preserved. A VM created before the engine persisted that shape has none recorded; re-run its original vm create (idempotent) once to stamp it.

Usage: delonix vm start [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # boot a stopped VM again with the disk, vcpus, memory and backend of its
  # last create — the overlay is reused, so its disk state survives
  delonix vm start dev

SEE ALSO:
  delonix vm stop · delonix vm restart · delonix vm create · delonix get

  delonix › vm › start

ExemplosExamples

Voltar a arrancar uma VM parada, sem repetir as flags do create

Boot a stopped VM again, without repeating the create flags

delonix vm start dev

`vm unbridge`

Tear down a vm bridge (dry-run without --apply).

Removes the subnets vm bridge --apply recorded. A bridge made before that record existed falls back to the auto-detected virbr*.

Usage: delonix vm unbridge [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --vm-subnet <VM_SUBNET>
          VM subnet(s) to close as well (default: the ones `vm bridge` recorded). Repeatable

      --apply
          Actually run the privileged teardown (requires root). Without it: dry-run

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # what the teardown would remove, without removing it
  delonix vm unbridge app

  # actually tear the veth and the routes down, as root — the subnets `vm
  # bridge --apply` recorded, whatever `virbr*` exists now
  sudo delonix vm unbridge app --apply

  # also close a subnet a bridge from before the record opened
  sudo delonix vm unbridge app --apply --vm-subnet 192.168.200.0/24

SEE ALSO:
  delonix vm bridge · delonix vm reach · delonix network ls

  delonix › vm › unbridge

ExemplosExamples

Fechar a ponte VM↔container — as subnets que o `vm bridge --apply` registou

Close the VM↔container bridge — the subnets `vm bridge --apply` recorded

sudo delonix vm unbridge minha-rede --apply

Fechar também uma subnet de uma ponte anterior ao registo

Also close a subnet from a bridge older than the record

sudo delonix vm unbridge minha-rede --apply --vm-subnet 192.168.200.0/24

`vm bridge`

EXPERIMENTAL (root): give a libvirt VM DIRECT IP reachability to a container SDN network.

A veth from the host into the holder netns, plus routes. Defaults to a DRY-RUN; add --apply (as root) to establish it.

Usage: delonix vm bridge [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --vm-subnet <VM_SUBNET>
          VM subnet(s) to route back (default: auto-detected `virbr*`). Repeatable

      --apply
          Actually run the privileged plan (requires root). Without it: dry-run

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # read the privileged plan before running any of it — without `--apply` this
  # only prints
  delonix vm bridge app

  # establish it as root: the VM then reaches container IPs on that network
  # directly, no published port needed
  sudo delonix vm bridge app --apply

  # route back a VM subnet the `virbr*` auto-detection did not find
  sudo delonix vm bridge app --apply --vm-subnet 192.168.122.0/24

SEE ALSO:
  delonix vm unbridge · delonix vm reach · delonix network create · delonix vm
  create

  delonix › vm › bridge

ExemplosExamples

Ver o plano SEM aplicar (o default é dry-run)

See the plan WITHOUT applying it (dry-run is the default)

delonix vm bridge minha-rede

Aplicar mesmo — precisa de root, é a excepção deliberada ao rootless

Actually apply it — needs root, the deliberate exception to rootless

sudo delonix vm bridge minha-rede --apply

`vm reach`

Which published ports a VM can actually reach, and how to fix the rest.

A port published to the default 127.0.0.1 is invisible to a VM — this lists the libvirt gateways, reads each port's LIVE bind, and for every loopback-only one prints the exact republish command.

Usage: delonix vm reach [OPTIONS]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # which published container ports a VM can actually get to, and the exact
  # republish command for each one that is stuck on loopback
  delonix vm reach

SEE ALSO:
  delonix vm bridge · delonix container port · delonix net ingress publish ·
  delonix get

  delonix › vm › reach

ExemplosExamples

Que portas de container é que as VMs conseguem alcançar

Which container ports VMs can reach

delonix vm reach

`vm vnc`

Print the VNC address of a graphical VM (created with --vnc, libvirt)

Usage: delonix vm vnc [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # the address to point a VNC client at, for a VM created with `--vnc` on
  # libvirt
  delonix vm vnc dev

SEE ALSO:
  delonix vm console · delonix vm create · delonix get

  delonix › vm › vnc

ExemplosExamples

Abrir o ecrã gráfico da VM

Open the VM's graphical screen

delonix vm vnc dev

`vm console`

Attach to the VM's serial console (interactive terminal).

Works with no IP (boot logs, login). Escape: Ctrl-D .

Usage: delonix vm console [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
  -e, --escape <ESCAPE>
          Key that detaches the console, as `^X` (default `^D`). Also settable via `$DELONIX_CONSOLE_ESCAPE`

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # watch the boot and log in before there is any IP or SSH — Ctrl-D brings
  # you back to the host
  delonix vm console dev

SEE ALSO:
  delonix vm vnc · delonix get · delonix vm create · delonix vm restart

  delonix › vm › console

ExemplosExamples

Consola série (voltar ao host: Ctrl+])

Serial console (back to the host: Ctrl+])

delonix vm console dev

`vm push`

Push a local golden VM image to an OCI registry (vm push <name> <target>)

Usage: delonix vm push [OPTIONS] <NAME> [TARGET]

Arguments:
  <NAME>
          

  [TARGET]
          Destination. Omit it to publish to the OFFICIAL repository this image belongs in (decided from the image's own metadata)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # publish an image you built to a registry of your own
  delonix vm push lab:1.0 ghcr.io/acme/lab:1.0

  # omit the target and it goes to the official repository the image's own
  # metadata names
  delonix vm push delonix-vm-k8s:1.34

SEE ALSO:
  delonix vm pull · delonix image vm build · delonix vm ls-remote · delonix
  image vm ls

  delonix › vm › push

ExemplosExamples

Publicar a tua imagem como artefacto OCI

Publish your image as an OCI artifact

printf '%s' "$GHCR_TOKEN" | delonix image login ghcr.io --username aminhaorg
delonix vm push minha-base:1.0 ghcr.io/aminhaorg/minha-base:1.0

`vm ls-remote`

List the tags available in a remote OCI repository.

With no argument, the OFFICIAL Delonix golden image repo (discover which k8s versions are published before pull).

Usage: delonix vm ls-remote [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --no-k8s
          With no `source`, list the official NO-Kubernetes golden's repo instead of the Kubernetes one

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # which Kubernetes versions are published, before spending a pull on one
  delonix vm ls-remote

  # the tags of the Kubernetes-free golden
  delonix vm ls-remote --no-k8s

  # any other OCI repository holding VM images
  delonix vm ls-remote ghcr.io/angolardevops/delonix-vm-base

SEE ALSO:
  delonix vm pull · delonix image vm ls · delonix vm push

  delonix › vm › ls-remote

ExemplosExamples

Que versões existem publicadas, antes de puxar

Which versions are published, before pulling

delonix vm ls-remote

As tags de um repositório teu

The tags of a repository of yours

delonix vm ls-remote ghcr.io/aminhaorg/base

`vm pull`

Pull a golden VM image from an OCI registry.

With no argument, the OFFICIAL Delonix image (ready for vm create/cluster kubeadm).

Usage: delonix vm pull [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]
          OCI reference (default: the official Delonix image)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --name <NAME>
          Local name (default: derived from the reference)

      --no-k8s
          With no `source`, pull the official NO-Kubernetes golden (just the `delonix` engine, rootless-ready) instead of the Kubernetes one

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # the official Kubernetes golden image, with kubeadm and the CRI already
  # installed
  delonix vm pull

  # the Kubernetes-free golden instead — just the engine, rootless-ready
  delonix vm pull --no-k8s

  # one published tag in particular, under a local name of your own
  delonix vm pull ghcr.io/angolardevops/delonix-vm-k8s:1.35 --name k8s-1.35

SEE ALSO:
  delonix vm ls-remote · delonix image vm ls · delonix vm create · delonix
  cluster kubeadm

  delonix › vm › pull

ExemplosExamples

A golden oficial com Kubernetes (sem argumento)

The official golden image with Kubernetes (no argument)

delonix vm pull

A golden SEM Kubernetes — só o motor, pronta a rootless

The golden image WITHOUT Kubernetes — just the engine, rootless-ready

delonix vm pull --no-k8s

De um registo teu, com nome local próprio

From a registry of yours, with your own local name

delonix vm pull ghcr.io/aminhaorg/base:24.04 --name base:24.04

`vm init`

Bootstrap a project with a VM manifest.

Files ALREADY FILLED IN (images included), ready to use without editing anything.

Usage: delonix vm init [OPTIONS] [DIR]

Arguments:
  [DIR]
          Project directory (default: the current one)
          
          [default: .]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --name <NAME>
          Project name (default: the directory name)

      --image <IMAGE>
          Image to use. Omit = fills in with the default image

      --force
          Overwrite existing files

      --vmfile
          Scaffold a `VMfile` for BUILDING your own qcow2 image, instead of a manifest for RUNNING an existing one. The two are different jobs and this is the same verb for both: `init` starts a project either way

  -t, --template <TEMPLATE>
          Generate a complete PROJECT for a stack (e.g. `python`) with best practices, instead of the generic scaffold. `--template list` shows the available ones

  -v, --template-version <TEMPLATE_VERSION>
          Version parameter some templates read — an image tag, a framework version, or a toolchain version, depending on the template; the exact accepted form is documented in that template's own README. Refused with a clear error on a template that has none

      --up
          After generating, build the image, start it, and wait until healthy

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # a `kind: VirtualMachine` manifest already filled in, applicable as it is
  delonix vm init

  # name the project and pin the image it should boot
  delonix vm init --name lab --image delonix-vm-base:ubuntu-24.04

  # a `VMfile` instead — the recipe for building your own qcow2, not for
  # running an existing one
  delonix vm init --vmfile

  # generate into a directory of its own, overwriting what is there
  delonix vm init ./lab --name lab --force

SEE ALSO:
  delonix vm apply · delonix image vm build · delonix vm create · delonix
  stack init

  delonix › vm › init

ExemplosExamples

Projecto com manifesto, pronto a correr

Project with a manifest, ready to run

delonix vm init --name lab

Scaffold de um VMfile para CONSTRUIR a tua imagem

Scaffold a VMfile to BUILD your image

delonix vm init --vmfile --name minha-base

`vm create`

Create (or auto-recover) a VM

Usage: delonix vm create [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --url-img <URL_IMG>
          Absolute URL of a qcow2 cloud image to boot this VM from.
          
          Downloaded once and cached, so a second `create` from the same URL costs nothing. Verified against a sibling `<url>.sha256` when the publisher offers one; without it, the download is trusted on TLS alone and SAYS SO — someone pointing this at their own bucket deserves to know which of the two they got.

      --disk <DISK>
          Base disk (qcow2/raw) — becomes a per-VM overlay. Omit to use the local golden VM image (if there is exactly one; `image vm ls`)

      --vcpus <VCPUS>
          vCPUs (default: 1, or the image's `VCPUS` — see `HYPERVISOR`/`VCPUS` in `delonix vm init --vmfile` — when `--disk` names a local image)

      --memory <MEMORY>
          Memory (`"2G"`/`"1024M"`; default: `1G`, or the image's `MEMORY` when `--disk` names a local image)

      --network <NETWORK>
          Ingress network for the tap (default: the system ingress network; a custom network must be created first with `delonix network create`)
          
          [default: ingress]

      --namespace <NAMESPACE>
          Isolation namespace (default `default`): VMs of different namespaces do not reach each other. Requires `--backend cloud-hypervisor`

      --kernel <KERNEL>
          Kernel for direct boot

      --initrd <INITRD>
          

      --firmware <FIRMWARE>
          Firmware, alternative to the kernel (cloud images)

      --cmdline <CMDLINE>
          

      --seed <SEED>
          Ready-made cloud-init (NoCloud) ISO — if given, takes priority over `--hostname`/`--ssh-key`/`--user-data` (those generate the ISO; this uses it directly)

      --disk-size <DISK_SIZE_GIB>
          Disk size for the node, in GiB (e.g. `40`) — omit to inherit the image's own size.
          
          This is the number a tenant's storage quota is counted against: it is PROVISIONED, not consumed (the overlay is thin and grows with use). Cannot be smaller than the base image.

      --hostname <HOSTNAME>
          Hostname to apply on first boot (generates the NoCloud ISO if no explicit `--seed` is given)

      --ssh-key <SSH_KEYS>
          Authorized public SSH key, `ssh-ed25519 AAAA...` or `@path` to read from a file. Repeatable

      --user-data <USER_DATA>
          Your own cloud-init `user-data` (fully replaces the default-generated one) — full control for whoever needs it

      --restart-policy <RESTART_POLICY>
          `no`|`on-failure`|`always`

      --hugepages
          

      --cpu-affinity <CPU_AFFINITY>
          Core affinity, e.g. `8-15`

      --device <DEVICES>
          VFIO PCI passthrough, repeatable

      --backend <BACKEND>
          `cloud-hypervisor`|`libvirt` (omit: the image's `HYPERVISOR` if `--disk` names a local one, else `DELONIX_VM_BACKEND`/`vm default-backend`/auto-detection, in that order)

      --require <CAPABILITY>
          Capability the backend must support on this host (a catalog name such as `vm.snapshot.memory`; repeatable; `delonix provider ls` lists them). Refused before anything is created, and auto-detection only picks a backend that has them all

      --net-mode <NET_MODE>
          libvirt only: `user`|`nat`|`bridge`

      --bridge <BRIDGE>
          Bridge name (net-mode=bridge) or libvirt network (nat)

      --ip <IP>
          Static IP (libvirt nat mode): DHCP reservation on the libvirt network

      --allow-mac-spoofing
          libvirt nat/bridge only: do NOT attach the anti-spoofing filter to this VM's NIC, so the guest may send frames with any source MAC (a nested hypervisor's guests on a bridge need it). Weakens isolation on the L2; off by default, persisted, shown by `vm describe` (ADR-0055)

      --vnc
          VNC graphical console (libvirt backend only — Cloud Hypervisor has no display)

      --console
          After starting, attach to the serial console to watch the boot live (Ctrl-D to detach)

      --wait
          After starting, wait (with a spinner) until the VM has an IP, up to --boot-timeout

      --boot-timeout <BOOT_TIMEOUT>
          Seconds to wait with --wait (default 120)
          
          [default: 120]

      --rm
          Throwaway VM: destroy it, with all its artifacts, as soon as it is stopped (`vm stop`, or a poweroff from inside the guest) — the VM twin of `container run --rm`

      --rm-after <DURATION>
          Like `--rm`, but keep the stopped VM for this long first (`30s`, `10m`, `2h`, `1d`) so a proof of concept can be inspected or restarted before it goes

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # from the local golden image, blocking until it answers on an address
  delonix vm create dev --vcpus 2 --memory 4G --wait

  # with your key and hostname applied on the first boot, by cloud-init
  delonix vm create dev --ssh-key @$HOME/.ssh/id_ed25519.pub --hostname dev --wait

  # a Kubernetes node on libvirt, on a NAT network so the IP is visible and
  # routable
  delonix vm create k8s-cp1 --disk delonix-vm-k8s:1.34 --backend libvirt --net-mode nat --vcpus 2 --memory 4G

  # isolated from other namespaces — only cloud-hypervisor puts the tap in the
  # SDN where that is enforced
  delonix vm create nas --backend cloud-hypervisor --namespace teamA

  # a hypervisor whose own guests bridge onto the network — drops the MAC/ARP
  # anti-spoofing filter for THIS VM only, and `vm describe` says so
  delonix vm create pve1 --disk proxmox-ve:9.2 --backend libvirt --net-mode nat --allow-mac-spoofing

SEE ALSO:
  delonix vm ls · delonix vm console · delonix vm start · delonix image vm
  pull

  delonix › vm › create

ExemplosExamples

VM a partir da imagem dourada, com chave SSH — o nome é POSICIONAL

VM from the golden image, with an SSH key — the name is POSITIONAL

delonix vm create node1 --disk k8s-golden --vcpus 2 --memory 4G --ssh-key @~/.ssh/id_ed25519.pub

Sem `--disk`, usa a imagem VM dourada local — se houver exactamente uma

With no `--disk`, it uses the local golden VM image — if there is exactly one

delonix vm create node1 --ssh-key @~/.ssh/id_ed25519.pub

`vm ls`

List the VMs

Usage: delonix vm ls [OPTIONS]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --ports
          Also probe a short list of well-known ports (22, 6443, 10250, 80, 443) on each VM's IP and show which respond — a real TCP connect per port, short timeout, run concurrently. Off by default: unlike the rest of `ls` (local state only), this does live network I/O and can add latency, especially for an unreachable/booting VM

  -o, --output <OUTPUT>
          Output format: `table` (default) or `json` (ADR-0005). The `ports_open` field is included only with `--ports` (same as the table column — the probe does live network I/O, off by default)
          
          [default: table]
          [possible values: table, json]

  -A, --all
          Also list the VMs that are not up (stopped or crashed).
          
          Without it `ls` shows what is UP — running or paused — the same cut `docker ps` makes.

      --namespace <NAMESPACE>
          Show only the VMs of this isolation namespace (see `vm create --namespace`). Omit to list every namespace.
          
          Filtering is the only way to read a namespace off this listing on a host that uses none: the NAMESPACE column hides itself when every row would say `default`. Passing the flag prints the value verbatim instead, so the filter is visible in its own output.

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # every VM, with vcpus, memory, state and the IP it got
  delonix vm ls

  # also knock on 22/6443/10250/80/443 to see what already answers — live
  # network I/O, so it is off by default
  delonix vm ls --ports

  # the same rows as JSON, for a script
  delonix vm ls -o json

  # only one isolation namespace — and the NAMESPACE column stays, which it
  # does not when every row would say `default`
  delonix vm ls --namespace teamA

SEE ALSO:
  delonix get · delonix describe · delonix dashboard · delonix vm prune ·
  delonix image vm ls

  delonix › vm › ls

ExemplosExamples

delonix vm ls

`vm stop`

Stop the VM (preserves disk, record and snapshots)

Usage: delonix vm stop [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # give the host back its CPU and RAM, keeping the disk, the record and the
  # snapshots — the libvirt domain is undefined here, so its snapshot metadata
  # is preserved on our side and given back on the next start
  delonix vm stop dev

SEE ALSO:
  delonix vm start · delonix vm snapshot · delonix delete · delonix vm ls

  delonix › vm › stop

ExemplosExamples

delonix vm stop node1

`vm apply`

Apply the kind: VirtualMachine documents of a manifest.

delonix_vm::create is already idempotent by name — creates or auto-recovers.

Usage: delonix vm apply [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # apply the `kind: VirtualMachine` documents of ./delonix-manifest.yaml —
  # idempotent by name, so it creates or recovers
  delonix vm apply

  # from a manifest of your own
  delonix vm apply -f examples/vm.yaml

SEE ALSO:
  delonix vm init · delonix stack apply · delonix stack plan · delonix vm
  create

  delonix › vm › apply

ExemplosExamples

delonix vm apply -f delonix-manifest.yaml

LaboratórioLab

Cria uma microVM com cloud-init automático e liga-te por SSH.

delonix vm create dev --hostname dev --ssh-key ~/.ssh/id_ed25519.pub
delonix describe vm dev
delonix vm ssh dev

Create a microVM with automatic cloud-init and SSH into it.

delonix vm create dev --hostname dev --ssh-key ~/.ssh/id_ed25519.pub
delonix describe vm dev
delonix vm ssh dev

DesafioChallenge

Só no backend libvirt: tira um snapshot da VM a correr, muda alguma coisa lá dentro, e usa restore para voltar atrás. Confirma que a mudança desapareceu.

delonix vm snapshot create dev antes-da-mudanca
delonix vm snapshot restore dev antes-da-mudanca

libvirt backend only: take a snapshot of the running VM, change something inside it, then use restore to roll back. Confirm the change is gone.

delonix vm snapshot create dev before-the-change
delonix vm snapshot restore dev before-the-change