Exclusive Access · Invitation Only

Creating Virtual Machines

A virtual machine is made from a registered image, or installed from an installation disc onto a blank disk. The node gives it CPUs, memory, a disk and one to four network interfaces, and starts it. A machine made from an image gets its own disk layered on the image, and its first boot is configured by the node. A machine installed from a disc is set up by its installer.

Part of Compute, in early access.

Create one

sudo cenvero-str-ctl vm create --name web-01 --tenant t-acme --image img-3f9a1c2e \
  --vcpus 2 --memory 2048 --disk 20 \
  --network net-acme --ssh-key-file ~/.ssh/id_ed25519.pub
FlagMeaningDefault
--nameLowercase letters, digits and hyphens, 1–63 characters, not starting or ending with a hyphen. Unique within its tenant on this noderequired
--imageThe base image's id. Required, unless --iso installs the machine from a disc—
--vcpusVirtual CPUs: from 1 up to the node's CPU count1
--memoryMemory in MiB: at least 128, at most the node's memory (machines together may add up to more)1024
--diskDisk size in GiB: at least the image's own size, at most 65536. For an install from a disc, use --disk-gibthe image's size
--disk-gibThe disk size for an install from a disc: at least 1 GiB. Required with --iso; if --disk is also given, the two must name the same size—
--isoInstall from a disc in the disc library (Installing from a disc). With no --image, the disk starts blank. With one, the image's disk is used and the disc is the first CD-ROM drive—
--driver-isoA disc for the second CD-ROM drive, such as a driver disc—
--boot-orderThe devices in the order they are tried, comma-separated: disk, cdrom0 (the first drive) and cdrom1 (the second). At create it may name only the drives the machine hasthe disk, then the discs
--protectedRefuses deletion until its protection is cleared (Options)off
--network NET or NET=IPAttach to a managed network, at its next free address or the one you name. Repeatable—
--public-ip auto or IPAn interface holding a public address your provider routes to this server. Repeatable—
--tenantThe customer the machine belongs tonone (an operator machine)
--placement autoIn a cluster, the cluster chooses the member that suits the machine best; a refusal lists each member's reasons. Not combined with --node (Placing machines)off: this node, or the member --node names
--anti-affinityThe machine's anti-affinity group: no other machine of its tenant with the same group runs on the same member. Needs --tenant, and every member running a version that supports it (Placing machines)none
--hostnameThe guest's hostnamethe name
--ssh-key-fileA public key file to authorize (every non-comment line is a key). Repeatable, up to 32 keys. Refused with --iso when there is no --image—
--user-data-fileYour own cloud-init user-data. Refused with --iso when there is no --image—
--dnsA DNS server for the guest. Repeatable, up to 3. Refused with --iso when there is no --imagethe node's upstream resolvers
--bandwidth-mbpsA bandwidth limit on each of the machine's interfacesnone
--no-startCreate it stoppedstarts it

The firmware (--firmware uefi, --secure-boot, --tpm) and the room a machine has to grow while it runs (--max-vcpus, --max-memory) are chosen at create too: see Firmware, resizing, interfaces and the guest agent.

A machine needs at least one --network or --public-ip, and has at most four interfaces in all. Public interfaces come first, so the guest's first interface is the one it is reachable on. How each kind is wired is on Networks and public addresses.

The node also needs at least 1 GiB free in its disk pool.

A create completes, or leaves nothing behind. A request that cannot be met — an image that is not ready, a network of another tenant, an address in use, a quota reached — is refused before anything is made, and a failure half-way is undone. If the machine is created but will not start, it is kept, stopped, with the reason in state_reason; fix the cause and run vm start.

First boot

The machine's first boot is configured through cloud-init: the node attaches a small read-only disk labelled cidata with three files, rebuilt from its records every time the machine starts. A machine installed from a disc with no image has none of this: its installer sets the addresses, users and hostname (Installing from a disc).

  • meta-data: the machine's instance id, its hostname and the SSH keys you gave.
  • network-config: one entry per interface, matched by its MAC address, with the interface's static address. The default route goes through the first public interface when there is one (see public addresses); otherwise through the first interface's network gateway, if that network has one. The first interface also carries the DNS servers.
  • user-data: your file, passed on exactly as you wrote it. It must start with #cloud-config or #! and be at most 64 KiB. Without one, the node sends only what sets the hostname.

cloud-init applies these once, on the machine's first boot; what the guest changes afterwards is its own. SSH keys and user-data are kept on the node only, readable by root; vm show reports how many keys and how many bytes of user-data a machine has, never their content.

#cloud-config
packages: [nginx]
runcmd:
  - systemctl enable --now nginx
sudo cenvero-str-ctl vm create --name www --tenant t-acme --image img-3f9a1c2e \
  --vcpus 2 --memory 2048 --network net-acme --user-data-file ./www.yaml

Changing the first-boot settings

vm cloud-init set changes a machine's hostname, DNS servers, SSH keys and user-data. It applies to a machine made from an image:

sudo cenvero-str-ctl vm cloud-init set vm-3f9a1c2e --hostname web-02 --dns 192.0.2.53,192.0.2.54
sudo cenvero-str-ctl vm cloud-init set vm-3f9a1c2e --ssh-key-file ~/.ssh/id_ed25519.pub
sudo cenvero-str-ctl vm cloud-init set vm-3f9a1c2e --user-data-file ./www.yaml --apply-again
sudo cenvero-str-ctl vm cloud-init show vm-3f9a1c2e
  • The change reaches the machine at its next start. The guest reads the new settings when it boots.
  • A list you give replaces the one on the machine: --dns replaces the servers (an empty value clears them), and --ssh-key-file replaces the keys.
  • --apply-again makes the next start a new first boot for the guest, so its first-boot steps run again. Without it, a configured guest does not run them again. Use it only when the guest should configure itself again.
  • The same limits as a create apply: a hostname of 1 to 63 lowercase letters, digits and hyphens; at most 3 DNS servers, given as IP addresses; at most 32 SSH keys; and user-data of at most 64 KiB that starts with #cloud-config or #!.
  • show gives the hostname, the DNS servers, each key's type and fingerprint, the user-data's size, and the settings' revision, an id that changes at every edit. It never shows a key or the user-data text, nor anything derived from the text.
  • A machine installed from a disc with no image refuses the change: "this machine was installed from a disc, so it has no cloud-init settings to change".

Installing from a disc

A machine installed from a disc with no --image starts with a blank disk, at least 1 GiB, and boots the installation disc in its first drive to run the installer. It has no image, so the node sends it no first-boot configuration: the installer sets its addresses, users and hostname. Create therefore refuses --ssh-key-file, --user-data-file and --dns for such a machine, with the message "a machine installed from a disc takes no SSH keys, DNS servers or user-data: those apply only to a machine made from an image". Give --image as well to keep those settings. The disc comes from the disc library.

sudo cenvero-str-ctl vm create --name db-1 --tenant t-acme --vcpus 2 --memory 4096 \
  --disk-gib 40 --iso iso-7d4e2f10 --network net-acme
  1. Create it. The machine is created and started. With --no-start it is created stopped, and it boots the disc at its next start.
  2. Open its graphical console in the web console, on the Console tab, and run the installer. The consoles page covers the consoles on the node.
  3. Set its addresses in the installer. Use the address the node gave the machine's interface: vm show lists it with the interface's MAC address. A tenant's machine can send traffic only from that address. Also set the network's gateway, if it has one, and the DNS servers you want.
  4. Eject the disc when the install is done. Use the id vm create printed: sudo cenvero-str-ctl vm cdrom set vm-3f9a1c2e --slot 0 --iso "". With the default boot order the disk is tried first, so the disc is used only when the disk cannot boot.

The console's create wizard starts the disk at 20 GiB. The command line needs --disk-gib, as above.

Windows

The wizard's Windows preset sets UEFI firmware and, where the node has one, a TPM 2.0 device. It asks for the driver disc in the second drive, and it does not pick that disc for you. The preset does not turn on secure boot. Nothing is injected into the media: Windows setup reads its storage driver from the driver disc. On the command line:

sudo cenvero-str-ctl vm create --name win-02 --tenant t-acme --vcpus 4 --memory 8192 \
  --disk-gib 60 --firmware uefi --tpm --iso iso-1a2b3c4d --driver-iso iso-2b3c4d5e \
  --network net-acme

--tpm needs a node that can give a TPM (compute status shows whether it can).

Windows installs are not verified on hosts without hardware virtualization. Those hosts run machines in software emulation, which is too slow to verify a Windows setup. No Windows install has been verified on a host with hardware virtualization yet either. Until this page says otherwise, treat Windows as untested.

Tenants

A machine with --tenant belongs to that customer:

  • it can attach only to that tenant's networks (and an operator machine, with no tenant, only to networks without one);
  • it is kept apart from every other tenant's machines and containers, on its own port, before it first runs (see Tenants);
  • it cannot be created or started while the tenant is suspended, and a suspension stops it (the resume starts it again if it was running — see Lifecycle);
  • the tenant cannot be deleted while it has machines.

To cap how many machines a tenant may have on this node (across the cluster once every member runs a version that supports it):

sudo cenvero-str-ctl tenant quota-set t-acme --max-vms 10
cenvero-str-ctl tenant quota t-acme        # max_vms and used_vms

0 means no cap. Lowering the cap never touches machines that already exist; it only refuses the next create.

Bandwidth. --bandwidth-mbps limits each of the machine's interfaces. It is refused for a tenant that already has a bandwidth cap: the tenant's cap applies to its machines (see Tenants & Bandwidth).

Looking at machines

cenvero-str-ctl vm list
cenvero-str-ctl vm list --tenant t-acme
cenvero-str-ctl vm show vm-3f9a1c2e
{
  "vm": {
    "id": "vm-3f9a1c2e",
    "name": "web-01",
    "tenant_id": "t-acme",
    "state": "running",
    "desired_state": "running",
    "state_reason": "",
    "flags": [],
    "vcpus": 2,
    "memory_mib": 2048,
    "disk_gib": 20,
    "image_id": "img-3f9a1c2e",
    "hostname": "web-01",
    "hypervisor": "kvm",
    "nics": [
      { "index": 0, "network_id": "net-acme", "ip": "10.30.0.20", "mac": "02:ce:0a:1e:00:14",
        "interface": "cnv-v-3f9a1c2e0", "bandwidth_mbps": 0 }
    ],
    "user_data_bytes": 0,
    "ssh_key_count": 1,
    "console_sessions": [],
    "created_at": "2026-09-28T09:20:11Z",
    "updated_at": "2026-09-28T09:21:02Z"
  }
}

state is what the machine is doing, desired_state what you last asked for; Lifecycle and restarts explains the states and the flags. hypervisor is kvm, or emulated on a node without hardware virtualization.

Changing a machine

CPUs and memory are changed with vm update, live on a running machine within its maximums; interfaces are added and removed with vm nic add and vm nic remove, also while it runs. Both are on Firmware, resizing, interfaces and the guest agent, with the guest agent (setting a password, the guest's own addresses).

Growing the disk

sudo cenvero-str-ctl vm stop vm-3f9a1c2e
sudo cenvero-str-ctl vm resize vm-3f9a1c2e --disk 40
sudo cenvero-str-ctl vm start vm-3f9a1c2e

The machine must be stopped, and a disk can only grow. The guest sees the new size on its next boot; most cloud images then grow their root file system to fit by themselves.

Deleting

sudo cenvero-str-ctl vm delete vm-3f9a1c2e --yes

A protected machine is not deleted. The delete is refused with "this machine is protected; clear its protection before you delete it", and nothing changes. Clear the protection first: sudo cenvero-str-ctl vm options set vm-3f9a1c2e --protected=false (Options). Starting, stopping, restarting and the consoles stay allowed on a protected machine.

A running machine is powered off at once (not shut down gracefully — stop it first if the guest should shut down cleanly), and its disk, its first-boot disk and its interfaces are removed. Its network addresses and public address are free again straight away. The disk's current data is gone, and its space is released without being overwritten first. Its backups are kept, as restore points you can restore into a new volume, and they stay until you delete them. A machine that has no backups leaves nothing behind (Snapshots, backups and schedules). A delete that is interrupted can be run again; it carries on where it stopped.

Over the API

curl -k -X POST "$NODE/api/v1/vms" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{
    "name": "web-01", "tenant_id": "t-acme", "image_id": "img-3f9a1c2e",
    "vcpus": 2, "memory_mib": 2048, "disk_gib": 20,
    "networks": [ { "network_id": "net-acme", "ip": "10.30.0.20" } ],
    "ssh_authorized_keys": [ "ssh-ed25519 AAAA… [email protected]" ],
    "user_data": "#cloud-config\npackages: [nginx]\n",
    "dns": [ "192.0.2.53" ],
    "start": true
  }'
MethodPathNotes
GET/api/v1/vms?tenant_id= for one tenant's
POST/api/v1/vms201 with the machine when the create finishes within 20 seconds. A longer create answers 202 with the machine's id and its task: follow the task (GET /api/v1/tasks/{id}), which ends succeeded or failed with the reason. Do not send the create again while it runs. A create still being prepared after 25 seconds answers 202 with no task and a message: list the machines to see whether it was created. Each networks entry has network_id (optionally ip) or public_ip, and optionally bandwidth_mbps. For an install from a disc, leave out image_id and give iso_id and disk_gib; driver_iso_id, boot_order and protected are optional
GET/api/v1/vms/{id}One machine
DELETE/api/v1/vms/{id}Delete it and its disk. 409 for a protected machine
POST/api/v1/vms/{id}/resize{"disk_gib": 40}, stopped machines only
GET/api/v1/vms/{id}/cloud-initThe first-boot settings, without their secrets
PUT/api/v1/vms/{id}/cloud-init{"hostname", "dns", "ssh_keys", "user_data", "apply_again"}, each optional. 200; 409 for a machine installed from a disc

Changing CPUs, memory, interfaces, drives and options, and the guest agent, have their calls on Firmware, resizing, interfaces and the guest agent.

Every change answers as described here and also names the task that records it ("task", and a Location header): who asked, what was done and how it ended — including a create that failed and was rolled back. A machine's history is GET /api/v1/tasks?object=vm-3f9a1c2e; see Tasks. GET /api/v1/resources lists every machine with its state in one answer.

Starting, stopping and restarting are on Lifecycle and restarts. Errors come back as {"error": "…"} in plain words: 400 for a request that is not valid, 404 for an unknown machine or image, 409 for a conflict (a name in use, a state that does not allow it, a quota reached), 503 while Compute is not ready, 403 when the licence does not allow it. Unknown fields in the body are refused, not ignored.

Tenant-scoped API keys cannot create or delete machines. Use the node's API token, an operator key, or an account or API token whose role allows it: creating a machine needs VM.Allocate on /vms or on its tenant, and the right to see the image and networks it names.

See also

↓ This page as JSON ↓ All documentation as JSON