Skip to main content
A VM is a long-lived virtual machine you provision on Lyceum Cloud, accessible over SSH. Unlike serverless Runs, VMs persist until you terminate them and bill for their entire uptime, regardless of whether anything is running on them.

​
Runs vs VMs

Use a VM when:
  • You need an interactive shell — for debugging, exploration, or development
  • Your environment is hard to express as a one-shot script (custom drivers, system packages, manual setup)
  • You want to keep state between sessions (model weights, datasets, conda envs)
  • You need to SSH in from another tool (a remote VS Code session, a port-forwarded service, a profiling tool)
Use a Run when:
  • The work is a one-shot job that has a defined start and end
  • You don’t need the machine after it finishes
  • You want to be billed only for active execution time

​
Lifecycle

VMs go through these states: pending / provisioning → running / ready → stopped / terminated / error A VM is billable from the moment it enters running, regardless of whether you’ve connected. Terminating it ends both the VM and the billing.

​
Storage on VMs

Each VM is provisioned with at least 100 GB of local disk, used for the OS, your code, and anything you write while the VM is running. This disk is wiped on termination — VMs are not durable storage. Your account’s S3 bucket is not auto-mounted on VMs (unlike Docker runs, where it’s mounted at /mnt/s3 by default). If you want bucket access from a VM, mount it yourself with s3fs, mc, rclone, or any other S3 client using credentials from POST /storage/credentials — see Storage. Attaching extra persistent volumes to a VM is not currently supported through the API; the dashboard exposes a placeholder for this feature.

​
Connecting

Once a VM is ready, fetch its IP and SSH in using the key you supplied at launch: 
lyceum vm status <vm_id>     # shows IP and connection info
ssh root@<ip-address>
The default SSH user depends on the image. If root doesn’t work, the VM detail in the dashboard or the API response will list the right username.

​
CLI

lyceum vm availability        # show profiles, $/GPU/hr, and supported GPU counts
lyceum vm list                # list your VMs
lyceum vm status <vm_id>      # status, IP, connection info
lyceum vm terminate <vm_id>   # terminate (use -f to skip confirmation)
lyceum vm availability prints a table of hardware profiles you can launch right now, their per-GPU hourly price, and which GPU-count configurations (1×, 2×, 4×, 8×) are currently supported. Use it before lyceum vm start to confirm capacity.

​
REST API

MethodEndpointPurpose
GET/vms/listList all your VMs
GET/vms/{vm_id}/statusStatus, IP, and connection info
GET/vms/availabilityCheck availability for a hardware profile
POST/vms/createProvision a new VM
DELETE/vms/{vm_id}Terminate a VM
For full request and response shapes see the API Reference.
Termination is permanent — the disk is wiped along with the VM. Save anything important to Storage before terminating, since your storage bucket persists across VMs.

Launch an instance

Provision a new GPU VM with your SSH key.