# Manage your VMs

## Creating a new VM

**CLI:**

Use the `compute vms create` command to create a VM of your choice. As an example, you can create a VM that uses a single Nvidia L40S GPU:

```sh
crusoe compute vms create \
  --name my-vm \
  --type l40s-48gb.1x \
  --location us-southcentral1-a \
  --image ubuntu22.04:latest \
  --keyfile ~/.ssh/id_ed25519.pub
```

You can find possible values for type and location by running `crusoe compute vms types` and `crusoe locations list` respectively.

If you don't specify an image, the VM will default to the latest version of ubuntu 22.04. Run `crusoe compute images list` for more options.
  **UI:**

To create a VM via the [console](https://console.crusoecloud.com):

1. From the console, select **Compute** > **[Instances](https://console.crusoecloud.com/compute/instances)** in the left nav.
2. Click **Create Instance**.
3. Follow the UI flow to input all required elements.
4. Click **Create**.
  **Terraform:**

Creating and accessing VMs is the first step to getting started on Crusoe Cloud. The following is intended to help get you started using Terraform to provision a VM in Crusoe Cloud.

Copy and paste the code below in a text-editor of your choice and name the file `main.tf`. The example below creates a VM that uses a single Nvidia A40 GPU called “my-vm”:

```hcl
// Crusoe Provider
terraform {
  required_providers {
    crusoe = {
      source  = "registry.terraform.io/crusoecloud/crusoe"
    }
  }
}

// local files
locals {
  ssh_key = file("~/.ssh/id_ed25519.pub") # replace with path to your public SSH key if different
}

// new VM
resource "crusoe_compute_instance" "my_vm" {
  name     = "my-vm"
  type     = "l40s-48gb.1x"
  location = "us-southcentral1-a"
  image    = "ubuntu22.04:latest" # use the 'latest' flag to get the most up to date image available from Crusoe

  ssh_key = local.ssh_key
}
```

`name`, `type`, `location` and `ssh_key` are required arguments. `default_project` is also required, but is typically specified in the config file, which is why it's omitted in the `crusoe_compute_instance` resource (see step 4 above). `image` is not required and for this example, we will use an `ubuntu22.04:latest` image.

After saving the code to a `main.tf` file, the following commands serve as the process to create a resource in Crusoe Cloud using Terraform:

`terraform init` - Initializes a working directory containing Terraform configuration files.

`terraform plan` - the output of this command will show the resources Terraform plans on creating.

`terraform apply` - this command will create the resources.

You can confirm that terraform successfully created the resources through the console, but if you prefer CLI, you can also run:
`crusoe compute vms list`

Which will show you the VMs you have created in your account.

## Viewing all existing VMs

**CLI:**

Use the `compute vms list` command to list all existing VMs.

```sh
crusoe compute vms list
```
  **UI:**

To list VMs via the [console](https://console.crusoecloud.com), go to the [Instances](https://console.crusoecloud.com/compute/instances) page.
  **Terraform:**

To list existing instances using Terraform, the following code snippet can be used to populate a Terraform data source using the Crusoe Terraform provider.

```hcl
# get instance with the specified ID
data "crusoe_compute_instance" "instance" {
  id = "<uuid of my instance>"
}

output "crusoe_instances" {
  value = data.crusoe_compute_instance.instance
}
```

## Update an existing VM

Currently, you can start or stop an existing VM. You can also update properties like VM type, IP address type, and Infiniband partition.

A stopped VM retains all data stored on that VM. An on-demand stopped VM is not billed, but a VM currently in an instance commitment is billed regardless of its state. Learn more about [VM billing](./overview#vm-billing).

**CLI:**

Use the `compute vms <stop|start|reset>` command to change the state of an already existing VM.

Use the `compute vms update <name>` command to make updates to the Infiniband partition, VM type, or public IP type via the `--ib-partition-id`, `--type`, or `--public-ip-type` flags, respectively.
  **UI:**

To update the state of a VM via the [console](https://console.crusoecloud.com):

1. From the console, select **Compute** > **[Instances](https://console.crusoecloud.com/compute/instances)** in the left nav.
2. Navigate to the row of the VM you want to update.
3. Under actions, select **Start** or **Stop**.

To update properties of a VM via the [console](https://console.crusoecloud.com):

1. Click on the name of the VM you want to update. This opens its details page.
2. Change its properties using the dropdowns or buttons.
  **Terraform:**

To update an existing instance using the Crusoe Terraform provider, you can change the fields of an existing instance resource and run `terraform apply`. The Crusoe Terraform provider will apply the changes to the instance.

```hcl
terraform {
  required_providers {
    crusoe = {
      source = "registry.terraform.io/crusoecloud/crusoe"
    }
  }
}

// new VM
resource "crusoe_compute_instance" "my_vm" {
  name     = "my-vm"
  type     = "l40s-48gb.1x"
  location = "us-southcentral1-a"
  image    = "ubuntu22.04:latest" # use the 'latest' flag to get the most up to date image available from Crusoe

  ssh_key = local.ssh_key

  disks = [
    {
      id = crusoe_storage_disk.data_disk.id
      mode = "read-only"
      attachment_type = "data"
    }
  ]
}
```

Currently, only the "network_interfaces" and "disks" of the instance can be changed. Changes to other fields of the instance will force a re-creation of the instance (deletion and then creation of a new instance).

### Updating state from within the VM

You can use standard `unix` commands like `shutdown` and `reboot` to change the state of a running VM. If you run `shutdown`, the VM will shut down and transition to the `Stopped` state. If you run `reboot`, the VM will reboot and will remain unreachable until it has fully restarted; however, the state will still be shown as `Running` throughout the restart.

## Deleting a VM

:::info
**Warning:** deleting a VM will also delete all data stored on the VM. Do not delete a VM unless you also wish to delete any downloaded or derived data.
:::

**CLI:**

Use the `compute vms delete` command to delete a VM of your choice. As an example, you can delete a VM by replacing `VM_NAME` with the name of the VM you wish to delete:

```sh
crusoe compute vms delete VM_NAME
```
  **UI:**

To delete a VM via the [console](https://console.crusoecloud.com):

1. From the console, select **Compute** > **[Instances](https://console.crusoecloud.com/compute/instances)** in the left nav.
2. Click on the VM you want to delete. This opens its details page.
3. Select **Delete Instance**.
4. Input the name of the VM in the input box and click **Confirm**.
  **Terraform:**

A VM can be deleted by using the `terraform destroy` command provided by the Terraform CLI tool.

If you are having issues creating or deleting VMs, please [contact support](../../resources/support.md).