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.
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:
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.
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).
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.
VM access and the CLI
You can configure, launch, wait, and connect from an interactive terminal. The Linux login istenant:
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 withrequests. 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.
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 thedisk value in the page URL. To list disks, call GET /v1/orchestrator/disks and use an entry’s id.
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-nulldeployedAt on the reservation means VMs were requested:
pendingOperation is activate, activate the reservation:
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.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 fromprovisioning 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.
5. Connect
Use theip, port, and tenant_username of a running VM. Do not assume port 22.
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’snode_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.resetpower-cycles the VM at once, like pressing its reset button. Anything not yet saved to disk is lost.
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.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.
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.
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. Usenvidia-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 overview
Compare VM and Bare Metal and understand the prerequisites for each.

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