Skip to main content
Launch VM access for an Ornn reservation, choose a disk, and SSH into your GPU environment. VM access is the default, recommended way to use your Ornn GPU reservation. Ornn launches a managed virtual machine on your reserved hardware, booted from your chosen disk with the active reservation SSH keys. Once the VM is ready, the SSH Host and connection details appear on the reservation detail page. In Nodes, the dot beside a VM reservation’s GPU type shows its current VM status. Hover over the dot to read the status label. Open the reservation for details. The Virtual Machines list includes a copyable SSH command for each VM once its connection details are available: ssh -p <port> tenant@<ip>.

Prerequisites

Before launching or switching to VM on a reservation:
  • You hold a Confirmed or Active reservation from an accepted offer or a Market purchase, visible in Nodes.
  • You have at least one active SSH public key registered on your account. See Manage SSH keys.

Set up VM access

1

Open the reservation detail page

From Nodes, click View on the reservation you want to configure. The detail page opens at /portfolio/[reservationId]. The legacy /portfolio/access URL redirects here.
2

Select VM

For a VM reservation, open its launch controls. Access mode follows the booked capacity; use the options shown for your reservation rather than assuming every listing supports both modes.
3

Choose a disk

Your reservation defaults to your organization’s newest disk, or an Ornn disk if your organization has none. Disk selection is separate from the order form. Open Nodes → your reservation → Disk to review or change it before launch. With only one available disk, the tab shows its details without a selector. Saving a choice does not launch your VM. After launch, the tab shows read-only disk details. If disk metadata is unavailable, the tab says so.Pick the disk Ornn should boot the machine from:
  • Ornn disk: a ready-to-use disk from Ornn, such as Ubuntu with the NVIDIA driver and CUDA installed.
  • Created disk: open Disks and choose Create disk to pick a base image plus optional Python, packages, CUDA, NVIDIA driver, and DCGM. See Disks.
  • Uploaded disk: open Disks and choose Upload disk to add a qcow2 from a file or a public URL. It boots as uploaded.
The disk selector shows a detail line with the selected disk’s software.
Pick your disk before launch. Changing the disk after launch is only available where the reservation detail page exposes it, typically by tearing down the current VM and relaunching with a new selection.
4

Attach an SSH key and launch

In the SSH Keys section, add or confirm an active reservation SSH key (use Add Key), then launch the VM. Ornn authorizes the active reservation keys on the machine.
5

Connect via SSH

Once the VM is ready, the SSH Host and User fields (plus a ready-to-run Quick Connect command) appear in the Connect section. Copy that command, including its port:
Each VM can use up to 2 TiB (2,048 GiB) of RAM, subject to its reserved capacity and memory available on the host. This limit applies to all GPU types.

What happens before your VM is ready

Open your reservation’s Virtual Machines tab to follow startup progress. Progress remains visible while activation is pending; a failed launch shows its status there as well. Before a VM’s SSH port opens, Ornn:
  • Checks that enough memory remains for the VM and its host. VM memory capacity reserves some physical RAM for host operation; a launch can fail if available memory has changed.
  • Isolates the VM on its host. VMs that share a host cannot reach each other over the host network, and a VM cannot reach the host’s management services.
  • Builds the disk if it is a created disk that has not been built yet. Ornn installs the disk’s software once, before your VM starts, so this first launch takes longer. Later launches boot the built disk directly. If the build fails, the launch fails and the disk shows Failed; the next launch from that disk retries the build.
  • Applies all pending Ubuntu security updates, including kernel updates. It reboots the VM when an update requires it and confirms your GPUs are still visible afterward. First boot takes a few minutes longer than booting the disk alone. If updates cannot be applied, the launch fails instead of exposing an unpatched VM.
Startup time also depends on the VM’s memory size, GPU initialization, and whether the disk still needs its first build. Ornn checks for security updates on every launch, including when the disk is cached. Each VM writes to its own copy, so updates installed in an earlier VM do not change the disk used for the next launch. If no security updates are pending, the security updater skips installation; any required update and reboot still finish before SSH becomes available. SSH sessions reach your VM with your real client address, so SSH_CLIENT, last, and tools such as fail2ban see where each connection comes from. Ornn resets connections that exceed a per-address limit on concurrent or new connections to the VM’s SSH port.

Spot VMs

A filled Spot reservation shows Waiting for VM in the Virtual Machines tab until its VM appears. Provisioning starts automatically; you do not need to attach nodes or accept the reservation. The tab then shows the VM’s status and connection details as they become available. The SSH Keys and Volume tabs use the same centered empty-state layout. Available account keys and buckets remain listed below so you can add them to the reservation. A filled spot bid starts its VM for you, from your organization’s newest disk, or the newest Ornn disk if your organization has none. A disk you upload or create becomes the disk your next spot VM uses; disks that failed to build are skipped. Add SSH keys and connect from its reservation detail page as above. After a spot VM ends, the reservation and the empty Virtual Machines panel show Stopped, and disk details are no longer shown. Cleanup removes your VM and its local disk. Other VMs on the same host keep their own disks and keep running. Export local files before stopping. Data saved to a separate storage volume remains subject to that volume’s lifecycle. Capacity becomes available again after cleanup is verified. If a launch fails, its GPUs remain reserved until the failed VM has been removed safely.

Disks

A VM always boots a disk. From Disks you can:
  • Upload disk — add a qcow2 from a file or a public URL. It boots as uploaded.
  • Create disk — choose a base image, a display name, and optional Python, packages, CUDA, NVIDIA driver, and DCGM. Python, CUDA, NVIDIA driver, and DCGM choices are limited to versions the base image’s Ubuntu release can install; packages without a Python choice install into the system Python. NVIDIA driver choices are 580 (proprietary), 580 (open), and 595 (open).
In Upload disk, select Upload a file and use Upload .qcow2 inside that option, or select Import from URL and enter the Disk URL inside that option. Create disk notes that the first build can take up to several minutes and how to contact support for a custom setup. Create disk warns when NVIDIA driver or DCGM is set to None. Without a driver, VMs from the disk can’t use NVIDIA GPUs unless the base image already includes one. Without DCGM, dcgmi diagnostics aren’t available in the VM. Select a disk in the list to open its details in a side panel without leaving Disks. The panel shows its size, software configuration, and checksum. A created disk builds the first time a VM launches it. That launch shows Building, and the disk becomes Ready once the built disk is saved; later launches skip the build. A disk whose build failed shows Failed with the reason, and the next launch from it retries the build. Before you buy or launch, a note under the disk choice says when the chosen disk has not been built yet or its last build failed. Disks with the NVIDIA driver use Ubuntu’s signed driver packages, and the VM’s automatic security updates keep them current. If an update installs a new driver while the VM runs, CUDA programs can report a driver version mismatch until you reboot the VM.
Need a custom setup that the disk builder does not list? Email Ornn support. An uploaded disk must include cloud-init and the qemu-guest-agent service, which Ornn uses to deliver your SSH keys and mount storage. Bucket mounting also requires GCSFuse and FUSE tools. New disk builds include these dependencies; already-built disks and running VMs keep their existing software. Contact support if an older disk needs storage tools. Keep qemu-guest-agent running: Ornn checks it every 5 minutes, and if it does not answer two checks in a row, Ornn reboots the VM to bring it back (a normal reboot, then a hard reset if needed). A reboot stops anything running on the VM.
Switching access modes (VM ↔ Bare Metal) after launch tears down the existing environment. Anything stored on the VM that isn’t persisted off the host will be lost.
Deleting a VM removes that VM’s writable local disk and access. It preserves other VMs and the disk the VM booted from. Newly provisioned local disks are encrypted with a separate key per VM; deletion retires that key after the VM has stopped. Attached storage volumes follow their own retention and deletion settings.

VM access and the CLI

You can configure, launch, wait, and connect from an interactive terminal. The Linux login is tenant:
ornn connect opens an interactive session with your local OpenSSH client. ornn check reports lifecycle, health, metrics, and logs. See the CLI reference for monitoring and automation options. After you connect, verify GPUs with nvidia-smi on NVIDIA hosts or amd-smi list on AMD Instinct. Use a disk with a driver and compute runtime compatible with your GPU: CUDA for NVIDIA or ROCm for supported AMD GPUs. The available GPU counts and connectivity depend on the reserved hardware’s supported configuration. For a multi-GPU NVIDIA VM, use nvidia-smi topo -m to inspect connectivity between the GPUs assigned to your VM. NV entries identify NVLink connections. Direct GPU-to-GPU (peer-to-peer) transfers are enabled between GPUs that share a PCIe switch, and each such pair is verified when the VM launches; check with nvidia-smi topo -p2p r. Between GPUs where peers show as not supported, frameworks such as NCCL still work and copy through host memory instead. GPU visibility alone does not prove compute or communication works; run a CUDA or ROCm workload and your application’s multi-GPU test after installing the driver and software required by your selected disk. When a VM uses every GPU on its machine and the machine has spare local NVMe data drives, the VM also gets those drives, encrypted and mounted at /data (then /data1, /data2, …) and owned by your user. They keep their contents when you reboot or reimage the VM, and are erased when the VM is deleted. Check for them with df -h /data; without spare drives, /data is not created. Choose or create disks from the web reservation detail page or Disks.

Use the API

You can run the same flow over HTTPS with an organization API key. Each step shows the CLI command where one exists, the REST request, and Python with requests. The API reference has the full request and response schemas. The examples use fictional IDs. Before you start:
  • Your organization is approved and holds a VM reservation.
  • Your organization has at least one active SSH key. Note its ID; see Manage SSH keys.
The Python examples share this setup:

1. Choose a disk before activation

This step is optional. Without a choice, Ornn uses your organization’s newest disk, or the newest Ornn disk, skipping a failed build when a disk that did not fail is available. To use a specific disk, open it in Disks; its ID is the disk value in the page URL. To list disks, call GET /v1/orchestrator/disks and use an entry’s id.
Saving a disk does not launch a VM. The CLI does not set reservation disks. After the reservation is activated, the disk is locked and this request returns 409 with reservation_disk_locked.

2. Wait for activation

When the reserved window starts, Ornn activates the reservation and creates one VM per reserved node from the chosen disk. A non-null deployedAt on the reservation means VMs were requested:
To start sooner within the window, or to retry when pendingOperation is activate, activate the reservation:
Activating an already activated reservation returns it unchanged. If the response is 409 with runtime_pending, repeat the same request.

3. Launch access

Launch delivers your SSH keys to the reservation’s VMs. If the reservation has no machines yet, launch starts provisioning them.
A 202 response means the VMs already exist and your keys are queued for them. A 201 response means launch started provisioning. Neither means SSH is ready. Once the reservation has machines, repeating launch does not create new VMs; it sends the keys again. In scripts, the CLI also needs the flags described in automation mode. The launch request accepts these fields: There is no size or storage field. Each VM receives its reserved GPUs and a matching share of the host’s vCPUs, memory, and local disk, with at most 2 TiB of RAM. Attach storage volumes separately. A 409 with ssh_key_required means your organization has no active SSH key. A 400 with disk_required means launch had to create VMs but no disk was saved or sent.

4. Wait for SSH

Poll the reservation’s VMs every five seconds with a deadline. Each VM moves from provisioning to running. Stop if a VM reports failure. The stages array shows the same launch progress as the Virtual Machines tab, from Preparing host to Configuring access. Connect only after status is running; tenant_username appears at that point. When launch created the VMs (201), your keys are installed before running. When the VMs already existed (202), your keys arrive in a separate push that can finish after running, so a Permission denied (publickey) in the first minutes means delivery is still in progress. The Python example retries a non-interactive SSH login until your key is accepted; you can also check delivery by fingerprint.
A timeout means the outcome is unknown, not that launch failed. Check the reservation in Nodes before launching again.

5. Connect

Use the ip, port, and tenant_username of a running VM. Do not assume port 22.
Run the printed command, then check your GPUs with nvidia-smi -L. If SSH reports Permission denied (publickey), your key may still be on its way. Repeat the launch request to send it again, or see troubleshooting.

Reboot a VM

Reboot restarts one VM in place. Its disk, GPUs, SSH port, and network stay the same, and other VMs on the node keep running. Use the VM’s node_id and id from the reservation’s VM list. In Nodes, open the VM and choose Reboot VM or Reset VM from its actions menu, or select several VMs and choose Reboot or Reset in the selection bar.
  • reboot (the default) asks the VM’s operating system to restart. If the VM has not come back within about 90 seconds, Ornn resets it.
  • reset power-cycles the VM at once, like pressing its reset button. Anything not yet saved to disk is lost.
A 202 response means the reboot is accepted. The VM stays running while operation is reboot; read the VM list until operation_status is succeeded, then reconnect. If the VM does not come back, operation_status is failed with a failure, and you can reboot again or reimage. A VM can be rebooted only while it is running, and not while another reboot, launch, or reimage is in progress.

Reimage a VM

Reimaging erases everything on the VM’s disk. Export local data first. Attached storage volumes and local data drives at /data are not erased.
Reimage rebuilds one VM from a disk you choose, without stopping the reservation. The VM keeps its id, hostname, node, GPUs, and size. Use the VM’s node_id and id from the reservation’s VM list, and a disk ID from Disks or GET /v1/orchestrator/disks. You can reimage a VM that is running or whose last start failed. A Kubernetes or Slurm worker can’t be reimaged. The new disk boots with the reservation’s selected SSH keys, or every active key on your account when none is selected. A VM on a private network stays private and keeps its private address. A created disk that has not been built yet builds during the reimage.
The CLI has no reimage command. A 202 response means the reimage is accepted. The VM returns to provisioning; wait for it as in step 4, Wait for SSH, then reconnect with the returned ip and port. The port can change. If the reimage fails, the VM shows failure, the reservation stays active, and you can reimage again.

Stop the reservation

Stopping ends the reservation now. Ornn revokes access and deletes every VM in the reservation together with its local disk. This cannot be undone. Export local data first.
There is no API route to delete a single VM. Stopping the reservation removes all of its VMs. For Spot, this is Stop VM; see How spot ends.
The CLI has no stop command. A 202 response means the stop is accepted and the VM is still being removed; read the reservation until endsAt is set. To switch the reservation to Bare Metal or change its network instead, see Switch access mode or network.

GPU monitoring

VM GPU measurements describe the GPUs assigned to your VM and require a working compatible driver inside it. Missing or stale readings mean that the current state is unknown; they do not mean zero usage or a healthy GPU. GPU allocation and available runtime measurements can differ while an environment is starting or recovering. Use nvidia-smi or amd-smi list inside your VM to inspect current visibility and verify your workload after installing or changing drivers.

What’s next

access

Access overview

Compare VM and Bare Metal and understand the prerequisites for each.
bare-metal-access

Bare Metal access

Connect directly to the GPU host when you need full hardware control.

Share an attached volume between Linux users

An attached Ornn object-storage volume is shared with all local Linux users on your machine. On a writable volume, users can read, create, edit, and delete files regardless of which user mounted the volume or created the file. Read-only volumes remain read-only for every user. Use the same mount path for each user. If you choose a custom path, its parent directories must allow those users to traverse them. Avoid simultaneous writes to the same file from multiple users or nodes; object storage does not provide POSIX file locking.