Launch a virtual machine

A virtual machine is the same idea on any engine: a named compute instance with CPU, memory, a boot disk, and a network. This guide provisions one end to end: describe the VM, submit the create request, track the operation it returns, and read the running VM back. The runnable examples target qibdo’s own engine, where the platform manages the full lifecycle. For how a VM behaves once it exists, on any engine, see Virtual machine lifecycle.

Before you begin

Authentication. Export an authenticated bearer token as QIBDO_API_TOKEN and the API base URL as QIBDO_BASE_URL. See Authenticate a user and manage the session.
Permissions. Your identity needs permission to create compute resources in the target workspace. See the authorization model.
Prerequisites. Export the target QIBDO_WORKSPACE and QIBDO_ZONE, and have a boot image to clone and a network to attach to.

Step 1: Describe the virtual machine

The create request takes the VM in its request body. At minimum you give it a name, a CPU and memory sizing, one or more disks (typically a boot disk cloned from an image), an operating system, and a network to attach to. You supply only the inputs and omit every output-only field (the assigned id, the live status, timestamps, and so on).

The name must be an RFC 1035 DNS label: lowercase, 1 to 62 characters, starting with a letter.

Rather than reproduce the request body here (it would drift as the contract evolves), build it from the authoritative schema, which lists every field, marks which are required, and marks which are output-only:

Create a virtual machine: the full request and response shape.

Save your request body to a file, for example vm.json, to submit in the next step.

Step 2: Submit the create request

Creating a VM is a POST to the VM collection under the parent workspace and zone. It returns an operation that records the request; the VM itself then provisions in the background.

curl -X POST \
  "$QIBDO_BASE_URL/compute/v1/workspaces/$QIBDO_WORKSPACE/zones/$QIBDO_ZONE/engines/qibdo/vms" \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @vm.json

For a create, the operation comes back already completed, with its resource_id set to the new VM’s id. The operation also reports which kind of change it represents (here, a create) and the type of resource it affects. Read the VM’s id from resource_id to use in the next steps.

Step 3: Check the create result

The create operation completes synchronously: the response already has a done status, progress at 100, and resource_id holding the new VM’s id. You can re-read any operation by its id:

Get an operation: the request, and the full set of status values and their meaning.

curl \
  "$QIBDO_BASE_URL/compute/v1/operations/<operation-id>" \
  -H "Authorization: Bearer $QIBDO_API_TOKEN"

A completed create operation looks like this, with resource_id holding the new VM’s id and progress at 100:

{
  "id": "<operation-id>",
  "operation_type": "COMPUTE_OPERATION_TYPE_CREATE",
  "resource_id": "<vm-id>",
  "resource_type": "VirtualMachine",
  "status": "COMPUTE_OPERATION_STATUS_DONE",
  "progress": 100
}

If the operation comes back with an error status instead, its errors array explains why, and no VM is created.

Step 4: Read the VM back

Fetch the VM with its id (the operation’s resource_id):

Get a virtual machine: the request, and the full VM response, field by field.

curl \
  "$QIBDO_BASE_URL/compute/v1/workspaces/$QIBDO_WORKSPACE/zones/$QIBDO_ZONE/engines/qibdo/vms/<vm-id>" \
  -H "Authorization: Bearer $QIBDO_API_TOKEN"

A freshly created VM starts in creating and advances to running on its own as the platform provisions it. Re-read it until its status is running. See Virtual machine lifecycle for the full state model and transitions.