CLICommands
orl vms create
Create a VM, part of the orl CLI for OpenRelay GPU VMs, pods, batches and billing. Usage, every flag and an example.
orl vms create --name <name> --ssh-key-ids <ssh-key-ids>Creates a GPU or CPU VM from the requested shape, image, disk and SSH keys and returns it as a VmSummary; a valid request with no free capacity answers 503.
Flags
| Flag | Type | Required | |
|---|---|---|---|
--idempotency-key | string | no | Makes a retried create safe. Choose one value per create you mean to make, 1 to 512 bytes (bytes, not characters), such as a UUID, and send it again on every retry of that create. The first request with a key runs, and a 2xx answer is kept for 24 hours: a repeat with the same key and the same body gets that answer back, with the same status and the header Idempotent-Replayed: true, and creates nothing. A batch create compares the body byte for byte; a VM or pod create compares the fields it decodes, so whitespace and key order do not count. A repeat while the first request is still running answers 409; repeat it a second later. The same key with a different body answers 422. An answer other than a 2xx is not kept, so a retry after a 4xx or a 5xx runs again. A 2xx too large to keep holds the key without it: every repeat answers 409 and creates nothing. Keys are scoped to the organization and the operation. |
--allow-fallback | bool | no | |
--cloud-init | string | no | Startup script run inside the guest the first time this VM boots. Must begin with a shebang (e.g. "#!/bin/bash"); a raw cloud-config document is rejected. Runs once per disk, not once per boot: a stop/start keeps the disk and does not re-run it, while a VM that lands on a fresh disk does. It runs as root once the network and your SSH keys are up, and its output goes to the VM's logs. A script that fails does not stop the VM from starting or from being billed, so check the logs rather than assuming it succeeded. |
--container-command | []string | no | |
--container-port | int | no | |
--disk-size-gb | int | no | Boot disk in GB. Omit to get the default, which for a GPU VM is 100 GB per GPU. That default is not a floor: a smaller size is accepted down to the platform minimum (minDiskGb on GET /v1/gpu-availability). The ceiling is the node's per-GPU disk share times gpuCount (perGpu.diskGb on its offer), so a one-GPU VM cannot take a whole node's VM dir, and the size must also be free on that node right now. |
--env-vars | map[string]string | no | |
--gpu-count | int | no | |
--gpu-model-id | string | no | |
--guest-mem-mb | int | no | Guest RAM for a GPU VM, in MiB. Omit for auto, which takes the tightest node that can give a full per-GPU share. At least 65% of the VRAM the VM is placed against (the catalog's floorPerGpu; a smaller request is raised to it), and at most some node's per-GPU share times gpuCount: a request above every node's share is rejected with VM_SHAPE_NOT_PLACEABLE, and one inside a share that no node has free right now with INSUFFICIENT_HOST_CAPACITY. Starting the VM after a stop, or re-dispatching it after its job is lost, starts it on its own node at no more than that node's current share (see requestedGuestMemMb). |
--health-check-path | string | no | |
--health-check-port | int | no | |
--health-checks | []string | no | |
--image-url | string | no | |
--kernel-modules | []string | no | |
--name | string | yes | |
--node-id | string | no | Place this VM on a specific node. Required to use capacity reserved to your org; omit to use the public pool. There is no fallback: if the node has no room for this GPU count the request is refused rather than placed elsewhere. A node you have no rights on reads as not found. |
--preferred-regions | []string | no | |
--privileged | bool | no | |
--public | bool | no | true = open endpoint (no data-plane auth); default false requires an org API key |
--resource-size | string | no | CPU-only VM machine size (the tier picker). Sending it alongside gpuCount is rejected with RESOURCE_SIZE_NOT_APPLICABLE: a GPU VM is sized from the host capacity its GPUs come with, not from this table. |
--ssh-key-ids | []string | yes | Org SSH key ids injected into the guest. At least one is required and every id must name a live key of this org: the data-plane gateway authorizes guest SSH against exactly this list, so a VM created without one has no SSH access. |
--template-id | string | no | |
--tier | string | no | |
--body | string | no | a JSON object of request body fields, merged under any of this command's own flags that are also set, e.g. {"key":"value"} |
--body-file | string | no | read the --body JSON object from a file (- for stdin) |
This wraps the createVm API operation.