> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyceum.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Your VMs

> Manage long-lived GPU virtual machines

A **VM** is a long-lived virtual machine you provision on Lyceum Cloud, accessible over SSH. Unlike serverless [Runs](/docs/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](/docs/serverless/runs) 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](/docs/configuration/storage#direct-s3-access).

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:

```bash theme={null}
lyceum vm status <vm_id>     # shows IP and connection info
ssh root@<ip-address>
```

<Note>
  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.
</Note>

## CLI

```bash theme={null}
lyceum vm availability        # show profiles, $/GPU/hr, and supported GPU counts
lyceum vm start               # provision a VM (-h profile, -k ssh-key, -g gpu-count)
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

| Method   | Endpoint              | Purpose                                   |
| -------- | --------------------- | ----------------------------------------- |
| `GET`    | `/vms/list`           | List all your VMs                         |
| `GET`    | `/vms/{vm_id}/status` | Status, IP, and connection info           |
| `GET`    | `/vms/availability`   | Check availability for a hardware profile |
| `POST`   | `/vms/create`         | Provision a new VM                        |
| `DELETE` | `/vms/{vm_id}`        | Terminate a VM                            |

For full request and response shapes see the [API Reference](/api-reference/introduction).

<Warning>
  Termination is permanent, the disk is wiped along with the VM. Save anything important to [Storage](/docs/configuration/storage) before terminating, since your storage bucket persists across VMs.
</Warning>

<Card title="Launch an instance" icon="plus" href="/docs/instances/launch">
  Provision a new GPU VM with your SSH key.
</Card>