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

# VM Lifecycle Management

> Save a new image from a running VM. This saves the file system and the state of the OS, including any running applications. You can preserve the original.

## Saving Images

> [!WARNING]
>
> **Deprecated in Orka 4.0.** `orka vm save` and `orka vm commit` create and update NFS-hosted images, which are deprecated and will be removed in a future Orka release. In Orka 4.0, both commands print a deprecation warning to stderr and show `(Deprecated)` in their help. Use [`orka vm push`](#orka-vm-push) to save a VM as an OCI image instead. To move existing images, see [Migrate NFS Orka images to OCI format with Harbor](https://docs.macstadium.com/orka/oci-images/orka-self-service-migrating-nfs-images-to-oci-with-harbor.md).

### orka vm save

Save a new image from a running VM. This saves the file system and the state of the OS, including any running applications. You can preserve the original image and deploy new VMs with the applied changes from the new image.

**Image Name Requirements:**

* Does not exceed 63 characters including the file extension (if set)
* Consists of lowercase alphanumeric characters, dashes (-) or periods (.)
* Must be unique to the cluster

**Note:** Saving a new image is an async operation. To check the status: `orka image list NEW_IMAGE_NAME`. This operation does not affect the original image of the VM. This operation restarts the VM.

**Syntax:**

```bash theme={null}
orka vm save VM_NAME NEW_IMAGE_NAME [--description 'DESCRIPTION'] [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-d, --description string   (Optional) Custom description for the new image
-h, --help                 Display help for save
-n, --namespace string     (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Save a new image from a running VM
orka vm save medium-ventura-vm 120gbmodifiedventura

# Save a new image from a VM in a specific namespace
orka vm save medium-ventura-vm 120gbmodifiedventura --namespace orka-test

# Save a new image with a custom description
orka vm save medium-ventura-vm 120gbmodifiedventura --description 'user@company.com saved this image'
```

### orka vm commit

Update an existing image from a running VM. Take the changes from the specified deployed VM and commit them back to its respective base image. On Orka 3.6 and earlier, for Intel-based VMs, the image must not be in use by any other VMs.

This operation applies any file system changes and the state of the OS, including any running applications, to the original image.

**Note:** Committing changes to an existing image is an async operation. To check the status: `orka image list IMAGE_NAME`. This operation restarts the VM.

**Syntax:**

```bash theme={null}
orka vm commit VM_NAME [--description 'DESCRIPTION'] [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-d, --description string   (Optional) New description for the original image
-h, --help                 Display help for commit
-n, --namespace string     (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Commit changes to the original image
orka vm commit small-ventura-vm

# Commit changes from a VM in a specific namespace
orka vm commit small-ventura-vm --namespace orka-test

# Commit changes and set a new description for the image
orka vm commit small-ventura-vm --description 'user@company.com updated this image'
```

## Pushing to OCI Registries

### orka vm push

(Apple silicon-only) The state of a running VM is saved on the host and pushed to an OCI-compatible registry.

The provided image must be in the following format: `server.com/repository/image:tag`. The `:tag` portion is optional and defaults to `latest` if not provided.

**Requirements:**

* Registry credentials must exist in the same namespace as the VM
* This is an async operation. To check the status: `orka vm get-push-status JOB_NAME`

**Syntax:**

```bash theme={null}
orka vm push VM_NAME IMAGE[:TAG] [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for push
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Push an image to GitHub Packages from a running VM
orka vm push vm-5rjn4 ghcr.io/myorg/orka-images/base:latest

# Push from a VM in a specific namespace
orka vm push vm-fxwj5 ghcr.io/myorg/orka-images/base:latest --namespace orka-test
```

### orka vm get-push-status

(Apple silicon-only) View the status of an image being pushed to an OCI-compatible registry. The status is viewable for one (1) hour after finishing, after which point the underlying job is cleaned up.

If a job name is not provided, the status of all current image push operations is shown. The job name is initially shown when the image push operation is started.

**Syntax:**

```bash theme={null}
orka vm get-push-status [JOB_NAME] [--namespace CURRENT_VM_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for get-push-status
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# View the status of all images being pushed
orka vm get-push-status

# View the status for a specific image by job name
orka vm get-push-status vm-push-qxjjf
```

## Resizing VM Disks

### orka vm resize

Resize the disk of a running VM. You can only increase the size of the disk.

Guest tools must be installed in the VM for Orka to resize and repartition the disk. Nothing else is needed after the command completes. Resize always assumes you're working in GB. This operation restarts the VM.

**Syntax:**

```bash theme={null}
orka vm resize VM_NAME NEW_DISK_SIZE [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for resize
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Resize a VM disk to 100GB
orka vm resize small-ventura-vm 100

# Resize a VM disk in a specific namespace
orka vm resize my-vm 100 --namespace orka-test
```

> **Intel-based VMs (Orka 3.6 and earlier)**
>
> On Orka 3.6 and earlier, Intel-based (amd64) VMs can provide SSH access credentials so Orka completes the resize and repartition automatically. Without them, you complete the repartition manually. Orka 4.0 removed the `--user` and `--password` options along with Intel support.
>
> ```bash theme={null}
> -p, --password string    (Optional) (Intel-only) SSH password for automatic repartition
> -u, --user string        (Optional) (Intel-only) SSH user for automatic repartition
> ```
>
> ```bash theme={null}
> # (Intel-only) Resize with automatic repartition
> orka3 vm resize small-intel-vm 100 --user admin --password admin
> ```
>
> You can then save or commit the modified image manually:
>
> ```bash theme={null}
> orka vm save VM_NAME NEW_IMAGE_NAME
> orka vm commit VM_NAME
> ```

## Power Operations (Intel Only, Orka 3.6 and Earlier)

> [!WARNING]
>
> **Removed in Orka 4.0.** `orka3 vm start`, `stop`, `suspend`, and `resume` only work on Intel-based VMs on Orka 3.6 and earlier. In Orka 4.0, which supports Apple silicon only, these commands return an unknown-command error. To restart an Apple silicon VM, delete it and deploy a new one.

**Note:** On Orka 3.6 and earlier, stopped or suspended VMs appear as 'Running' when listed with `orka vm list`.

### orka3 vm start

Power ON a stopped VM. The `orka3 vm stop` and `orka3 vm start` sequence acts as a VM reboot.

**Syntax:**

```bash theme={null}
orka3 vm start VM_NAME [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for start
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Power ON a stopped VM
orka3 vm start small-ventura-vm

# Power ON a VM in a specific namespace
orka3 vm start small-ventura-vm --namespace orka-test
```

### orka3 vm stop

Power OFF a running VM. The `orka3 vm stop` and `orka3 vm start` sequence acts as a VM reboot.

**Syntax:**

```bash theme={null}
orka3 vm stop VM_NAME [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for stop
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Power OFF a running VM
orka3 vm stop small-ventura-vm

# Power OFF a VM in a specific namespace
orka3 vm stop small-ventura-vm --namespace orka-test
```

### orka3 vm suspend

Suspend a running VM. This operation freezes all running processes on the VM, without turning it off. The `orka3 vm suspend` and `orka3 vm resume` sequence acts as putting the VM on hold then resuming it.

**Syntax:**

```bash theme={null}
orka3 vm suspend VM_NAME [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for suspend
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Suspend a running VM
orka3 vm suspend small-ventura-vm

# Suspend a VM in a specific namespace
orka3 vm suspend small-ventura-vm --namespace orka-test
```

### orka3 vm resume

Resume a suspended VM. This operation resumes all suspended processes on the VM, without turning it on.

**Syntax:**

```bash theme={null}
orka3 vm resume VM_NAME [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for resume
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Resume a suspended VM
orka3 vm resume small-ventura-vm

# Resume a VM in a specific namespace
orka3 vm resume small-ventura-vm --namespace orka-test
```

## Reverting VMs (Intel Only, Orka 3.6 and Earlier)

> [!WARNING]
>
> **Removed in Orka 4.0.** `orka3 vm revert` only works on Intel-based VMs on Orka 3.6 and earlier. In Orka 4.0 it returns an unknown-command error.

### orka3 vm revert

(Intel-only) Revert a VM to the latest state of its image. This operation restarts the VM.

> [!WARNING]
>
> This operation cannot be undone. Any unsaved or uncommitted data will be lost and unable to be retrieved.

**Syntax:**

```bash theme={null}
orka3 vm revert VM_NAME [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for revert
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Revert a VM to its original image state
orka3 vm revert small-ventura-vm

# Revert a VM in a specific namespace
orka3 vm revert small-ventura-vm --namespace orka-test
```


## Related topics

- [Bulk VM lifecycle management](https://docs.macstadium.com/remote-desktop-vdi/operations/bulk-vm-lifecycle.md)
- [OCI Registry Integration](https://docs.macstadium.com/orka/orka-cli-reference/oci-registry-integration.md)
- [MacStadium VDI 1.0 release notes](https://docs.macstadium.com/remote-desktop-vdi/macstadium-vdi-deployment/vdi-10-release-notes.md)
- [Shared responsibility guide](https://docs.macstadium.com/remote-desktop-vdi/reference/shared-user-responsibility-guide-for-macstadium-customers.md)
- [Ansible playbook implementation](https://docs.macstadium.com/remote-desktop-vdi/configuration/ansible-playbook-implementation.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.