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
| Flag | Meaning | Default |
|---|---|---|
--name | Lowercase letters, digits and hyphens, 1–63 characters, not starting or ending with a hyphen. Unique within its tenant on this node | required |
--image | The base image's id. Required, unless --iso installs the machine from a disc | — |
--vcpus | Virtual CPUs: from 1 up to the node's CPU count | 1 |
--memory | Memory in MiB: at least 128, at most the node's memory (machines together may add up to more) | 1024 |
--disk | Disk size in GiB: at least the image's own size, at most 65536. For an install from a disc, use --disk-gib | the image's size |
--disk-gib | The 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 | — |
--iso | Install 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-iso | A disc for the second CD-ROM drive, such as a driver disc | — |
--boot-order | The 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 has | the disk, then the discs |
--protected | Refuses deletion until its protection is cleared (Options) | off |
--network NET or NET=IP | Attach to a managed network, at its next free address or the one you name. Repeatable | — |
--public-ip auto or IP | An interface holding a public address your provider routes to this server. Repeatable | — |
--tenant | The customer the machine belongs to | none (an operator machine) |
--placement auto | In 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-affinity | The 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 |
--hostname | The guest's hostname | the name |
--ssh-key-file | A 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-file | Your own cloud-init user-data. Refused with --iso when there is no --image | — |
--dns | A DNS server for the guest. Repeatable, up to 3. Refused with --iso when there is no --image | the node's upstream resolvers |
--bandwidth-mbps | A bandwidth limit on each of the machine's interfaces | none |
--no-start | Create it stopped | starts 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-configor#!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:
--dnsreplaces the servers (an empty value clears them), and--ssh-key-filereplaces the keys. --apply-againmakes 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-configor#!. showgives 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
- Create it. The machine is created and started. With
--no-startit is created stopped, and it boots the disc at its next start. - 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.
- Set its addresses in the installer. Use the address the node gave the machine's interface:
vm showlists 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. - Eject the disc when the install is done. Use the id
vm createprinted: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
}'
| Method | Path | Notes |
|---|---|---|
GET | /api/v1/vms | ?tenant_id= for one tenant's |
POST | /api/v1/vms | 201 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-init | The 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.