delonix vm

Usage: delonix vm <COMMAND>

Commands:
  clone            Clone a VM into a new, independent one — its own disk, MAC and UUID (libvirt)
  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, memory and/or boot disk size 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)
  template         Mark a VM as a template: a frozen base for `vm clone`, which does not boot (libvirt)
  unpause          Resume a VM suspended with `pause`. Refuses a VM that is not paused
  update           Add vCPUs, memory, disks or NICs to a VM: live when it RUNS, for the next boot when STOPPED
  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`)
  image            VM image management — build/pull/push/ls/rm/describe/import/convert/init/ls-remote
  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:
  -h, --help
          Print help (see a summary with '-h')

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

EXAMPLES:
  # the official golden image, ready to boot without installing anything
  delonix vm image 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 vm image ls · delonix cluster kubeadm · delonix workload ls ·
  delonix container run

  delonix › vm

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)

  -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

Usage: delonix vm default-backend [OPTIONS]

Options:
      --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

Usage: delonix vm snapshot <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:
  -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

Usage: delonix vm restart [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --wait
          After starting, wait (with a spinner) until the VM answers, up to --boot-timeout; if it never does, exit 124 (DX-8503) and leave the VM running

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

  -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

Usage: delonix vm start [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --wait
          After starting, wait (with a spinner) until the VM answers, up to --boot-timeout; if it never does, exit 124 (DX-8503) and leave the VM running

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

  -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

Usage: delonix vm unbridge [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>
          

Options:
      --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

Usage: delonix vm bridge [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>
          

Options:
      --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

Usage: delonix vm reach

Options:
  -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

Usage: delonix vm vnc <NAME>

Arguments:
  <NAME>
          

Options:
  -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

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`

  -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

Usage: delonix vm image <COMMAND>

Commands:
  pull       Pull a VM image from an OCI registry
  push       Publish a local VM image to an OCI registry (single-blob artifact)
  rm         Remove a local VM image (its disk and its metadata)
  build      Build a VM image
  import     Register an existing disk image under a name, so `vm create --disk <name>` and `vm image push` can use it
  init       Scaffold a `VMfile` (and a cloud-init) for building your own image
  describe   Human-readable detail of one or more VM images, `kubectl describe` style
  ls         List the local VM images
  ls-remote  List the tags available in a remote OCI repository
  convert    Convert a VM disk between `qcow2` and `raw`
  help       Print this message or the help of the given subcommand(s)

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

COMMAND MAP:
  Lifecycle    rm · push · pull
  Create       import · init · build
  Inspect      ls · describe · ls-remote
  Maintenance  convert

EXAMPLES:
  # what golden images this node already has
  delonix vm image ls

  # fetch the official Kubernetes golden — the source is known, so no argument
  # is needed
  delonix vm image pull

  # build one of your own from a `VMfile`
  delonix vm image build -f VMfile -t myimage:1

SEE ALSO:
  delonix vm create · delonix image · delonix cluster kubeadm · delonix vm
  image build

  delonix › vm › image

Usage: delonix vm init [OPTIONS] [DIR]

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

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

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

      --force
          Overwrite existing files

  -t, --template <TEMPLATE>
          Generate a complete PROJECT for a stack (e.g. `fastapi`) 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

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

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

  delonix › vm › init

Usage: delonix vm create [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --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; `vm image ls`)

      --vcpus <VCPUS>
          vCPUs (default: 1, or the image's `VCPUS` — see `HYPERVISOR`/`VCPUS` in `delonix vm image init` — 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.

      --vcpus-max <VCPUS_MAX>
          Hotplug ceiling for vCPUs (ADR-0068 D3) — omit for no headroom (every VM without this flag stays exactly as it is today). Required, together with `--memory-max`, before `vm update` can add CPU/memory to this VM while it runs

      --memory-max <MEMORY_MAX>
          Hotplug ceiling for memory (ADR-0068 D3), same syntax as `--memory` — omit for no headroom

      --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 answers, up to --boot-timeout; if it never does, exit 124 (DX-8503) and leave the VM running

      --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 vm image
  pull

  delonix › vm › create

Usage: delonix vm ls [OPTIONS]

Options:
      --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.

      --credentials
          Add USER and PASSWORD: each VM's login (ADR-0048) — declared with `credentials:`, the documented default of an appliance image this repository builds, or `-`. The password shows where it lives (`(secret NAME)`), not its value

      --reveal
          With `--credentials`: print the password itself

  -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 vm image ls

  delonix › vm › ls

Usage: delonix vm stop <NAME>

Arguments:
  <NAME>
          

Options:
  -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

Usage: delonix vm apply [OPTIONS]

Options:
  -f, --file <FILE>
          

  -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/compute/virtualmachine.yaml

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

  delonix › vm › apply