CLICommands
orl pods create
Create a pod, part of the orl CLI for OpenRelay GPU VMs, pods, batches and billing. Usage, every flag and an example.
orl pods create --image <image> --ssh-key-ids <ssh-key-ids>Runs your container image as a pod on gpuCount whole GPUs of one node, with SSH access, at the on-demand rate fixed at creation, and returns it as a VmSummary. Compute-fabric pod (BYO container image + SSH keys): a hardened GPU container on gpuCount whole native-driver GPUs of one node. Admission claims free device-request GPU units (see listPodCapacity for what is claimable), snapshots the on-demand rate immutably onto the pod, and drives the guest workflow. A valid request the fleet has no room for right now answers 503 with a capacity code; a GPU count no node could ever hold for the org answers 400 GPU_COUNT_NOT_ALLOCATABLE; and an org without the pod tier answers 409 FEATURE_DISABLED.
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. |
--compute-class | on_demand, reserved, interruptible | no | purchase option. on_demand (pay per second, no commitment) is the only class sold; reserved is a deprecated alias that is stored as on_demand. interruptible is retired and rejected with 400 COMPUTE_CLASS_RETIRED; it remains listed only until the deprecation window closes. |
--env-vars | map[string]string | no | |
--gpu-count | int | no | how many whole GPUs this pod gets. All of them are claimed on ONE node and passed to the container together; the pod is priced for gpuCount GPUs. Omitted = 1. A count no single node could ever hold for your org is refused with 400 GPU_COUNT_NOT_ALLOCATABLE; one that some node could hold but none has free right now is refused with 503 INSUFFICIENT_GPU_CAPACITY (maxGpuCount on /v1/pods/capacity is the largest a create can take now). |
--gpu-model-id | string | no | |
--http-port | int | no | in-guest HTTP port exposed on the endpoint |
--image | string | yes | tenant container image ref (required) |
--name | string | no | |
--public | bool | no | true = open endpoint (no data-plane auth); default false requires an org API key |
--shm-size-gb | int | no | size of the pod's private /dev/shm in GiB (docker --shm-size). Optional; the maximum is half the pod's memory limit on its placement node (itself the pod's GPU-proportional share of node RAM), and a larger value is refused with 400 POD_ADMISSION_FAILED. Omitted lets the platform pick a safe default: that same maximum for a pod that owns its whole node, 2 GiB per GPU (capped at the maximum) for a shared multi-GPU pod, and docker's default for a shared single-GPU pod. Raise this when a multi-GPU NCCL / PyTorch DataLoader workload needs more shared memory than the default. |
--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 pod created without one has no SSH access. Attaching or detaching a key later takes effect within about a minute, with no restart. |
--volume-gb | int | no | size in GB of the pod's persistent volume, mounted read-write at /workspace. Omitted = 50. The volume lives on the pod's node and is kept across stop, start, restart, container crashes, node reboots and interruptions; it is deleted only when the pod is deleted (or after 7 days interrupted with its node gone). Everything outside /workspace is the container's own filesystem and is reset whenever the container is recreated. Fixed at create; there is no resize. |
--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 createPod API operation.