> ## 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 Deployment and Configuration

> VM configurations (templates) allow you to define reusable settings for deploying virtual machines. All VM configurations reside in the orka-default.

## VM Configuration Templates

VM configurations (templates) allow you to define reusable settings for deploying virtual machines. All VM configurations reside in the `orka-default` namespace and are available to all users and service accounts with access to orka-default.

The shorthand alias for `vm-config` is `vmc`.

### orka vm-config create

Create a VM configuration (template) with the specified settings. The required minimum configuration consists of a base image to use.

**VM Configuration Name Requirements:**

* Does not exceed 50 characters
* Consists of lowercase alphanumeric characters or dashes (-)
* Starts with an alphabetic character and ends with an alphanumeric character
* Must be unique to the cluster

**Syntax:**

```bash theme={null}
orka vm-config create VM_CONFIGURATION_NAME [flags]
```

**Options:**

```bash theme={null}
-c, --cpu int                (Optional) Number of CPU cores for the VM (default 3)
--disable-vnc                (Optional) Disable VNC (ensure SSH/Screen Sharing is enabled)
--display-dpi int            (Optional) DPI of the VM's virtual display
--display-height int         (Optional) Height of the VM's virtual display
--display-width int          (Optional) Width of the VM's virtual display
-h, --help                   Display help for create
-i, --image string           (Required) Base image (local or OCI)
-m, --memory float           (Optional) RAM in gigabytes
--node string                (Optional) Node on which to deploy the VM
--scheduler string           (Optional) Scheduler: 'default' or 'most-allocated'
--tag string                 (Optional) Node affinity tag
--tag-required               (Optional) Require tagged nodes for deployment
```

**Examples:**

```bash theme={null}
# Create a template for a VM using an OCI image
orka vmc create my-small-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --cpu 4

# Create a template using an image from your own OCI registry
orka vmc create my-oci-vm-config -i ghcr.io/my-organization/orka-images/orka-arm:latest --cpu 4

# Create a template with 5GB RAM
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --memory 5

# Create a template with flexible node affinity
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=false

# Create a template with strict node affinity
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=true

# Create a template that uses the most-allocated scheduler
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --scheduler most-allocated

# Create a template with disabled VNC
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --disable-vnc

# Create a template with a custom display size and DPI
orka vmc create my-medium-vm-config --image ghcr.io/macstadium/orka-images/tahoe:latest --display-width 2920 --display-height 1380 --display-dpi 100
```

> **Intel-only options (Orka 3.6 and earlier)**
>
> These options apply only to Intel-based (amd64) VMs on Orka 3.6 and earlier. They were removed in Orka 4.0, which supports Apple silicon only.
>
> ```bash theme={null}
> --disable-net-boost          (Optional) (Intel-only) Disables network performance boost
> -g, --gpu                    (Optional) (Intel-only) Enable GPU passthrough
> --iso string                 (Optional) (Intel-only) ISO name to attach
> --legacy-io                  (Optional) (Intel-only) Enable legacy IO, for High Sierra and Mojave VMs
> --system-serial string       (Optional) (Intel-only) Custom serial number
> ```
>
> ```bash theme={null}
> # (Intel-only) Create a template for an Intel-based VM
> orka vmc create medium-ventura-vm --image 90gbventurassh.img --cpu 6
>
> # (Intel-only) Create a template for OS install from ISO
> orka3 vmc create fresh-ventura-vm --image 90gbempty.img --iso ventura.iso
>
> # (Intel-only) Create a template with a custom serial number
> orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --system-serial A00BC123D4
>
> # (Intel-only) Create a template with GPU passthrough
> orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --gpu=true --disable-vnc
> ```

### orka vm-config list

Show basic or extended information about the available VM configurations. You can list all available configurations or show information about one or more specified VM configurations.

**Syntax:**

```bash theme={null}
orka vm-config list [VM_CONFIGURATION_1 [VM_CONFIGURATION_2 ...]] [--output wide|json] [flags]
```

**Options:**

```bash theme={null}
-h, --help            Display help for list
-o, --output string   (Optional) Output format: table (default)|wide|json
```

**Examples:**

```bash theme={null}
# List basic information about available VM configurations
orka vmc list

# List extended information
orka vmc list --output wide

# Show basic information about a specific VM configuration
orka vmc list small-ventura-vm

# Show extended information about a specific VM configuration
orka vmc list small-ventura-vm --output wide

# Show information about multiple VM configurations
orka vmc list small-ventura small-sonoma

# Return output as JSON
orka vmc list --output json
```

### orka vm-config delete

Delete the specified VM configurations (templates).

**Syntax:**

```bash theme={null}
orka vm-config delete VM_CONFIGURATION_NAME [VM_CONFIGURATION_NAME_2 ...] [flags]
```

**Options:**

```bash theme={null}
-h, --help   Display help for delete
```

**Examples:**

```bash theme={null}
# Delete a VM configuration
orka vmc delete small-ventura-arm-vm

# Delete multiple VM configurations
orka vmc delete medium-ventura-vm medium-ventura-arm-vm
```

## Deploying VMs

### orka vm deploy

Deploy a VM with the specified configuration. The minimum required configuration consists of an image and a number of CPU cores to assign to the VM.

**VM Name Behavior:**

* **When VM\_NAME is not provided:** Orka generates a unique name consisting of 'vm-' and a unique suffix
* **When VM\_NAME is provided:** Orka attempts to create the VM using the provided name (must be unique)
* **When both VM\_NAME and --generate-name are provided:** Orka generates a unique name based on VM\_NAME with a unique suffix

**VM Name Requirements (when provided):**

* Does not exceed 63 characters (including any generated suffix)
* Consists of lowercase alphanumeric characters or dashes (-)
* Starts with an alphabetic character and ends with an alphanumeric character
* Must be unique to the namespace

**Syntax:**

```bash theme={null}
orka vm deploy [VM_NAME] --image IMAGE_NAME [flags]
orka vm deploy [VM_NAME] --config VM_CONFIGURATION_NAME [flags]
```

**Options:**

```bash theme={null}
--config string              (Optional) VM template name
-c, --cpu int                (Optional) Number of CPU cores
--disable-vnc                (Optional) Disable VNC
--display-dpi int            (Optional) DPI of the VM's virtual display
--display-height int         (Optional) Height of the VM's virtual display
--display-width int          (Optional) Width of the VM's virtual display
--generate-name              (Optional) Generate unique name with suffix
-h, --help                   Display help for deploy
-i, --image string           (Required) Base image (local or OCI)
-m, --memory float           (Optional) RAM in gigabytes
--metadata stringToString    (Optional) Custom metadata (key1=value1,key2=value2)
--node string                (Optional) Specific node for deployment
-o, --output string          (Optional) Output format: json|wide
-p, --ports strings          (Optional) Port mapping (NODE_PORT:VM_PORT, optionally /tcp or /udp)
--scheduler string           (Optional) Scheduler: 'default' or 'most-allocated'
--tag string                 (Optional) Node affinity tag
--tag-required               (Optional) Require tagged nodes
--timeout int                (Optional) Deployment timeout in minutes (default 10)
--userdata string            (Optional) Bootstrap script run as root on the VM's first boot (file path or base64 string)
-n, --namespace string       (Optional) Namespace scope (default "orka-default")
```

**User Data:** `--userdata` requires Orka 4.0 or later and the Orka 4.0 orka-vm-tools in the image. The script runs once per VM, in the background, and doesn't delay the VM becoming available. Its output goes to `/var/log/orka/userdata.log` inside the VM, and `orka vm list --output wide` shows its progress in the `USERDATA-PHASE` column. For how the script runs, its limits, and an example, see [Bootstrap VMs with User Data](https://docs.macstadium.com/orka/orka-resources/userdata.md).

**Examples - Basic Deployments:**

```bash theme={null}
# Deploy a VM from an OCI image
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest

# Deploy a VM from an image in your own OCI registry
orka vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest

# Deploy with specified name, image, and CPU
orka vm deploy my-vm -i ghcr.io/macstadium/orka-images/tahoe:latest -c 4

# Deploy with unique name generation
orka vm deploy my-vm -i ghcr.io/macstadium/orka-images/tahoe:latest --generate-name

# Deploy with specified memory and random name
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest -m 10

# Deploy and display extended information
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --output wide

# Deploy with custom timeout
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --timeout 1
```

**Examples - Targeted Deployments:**

```bash theme={null}
# Deploy on a selected node
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --node mini-arm-14

# Deploy on a selected node in a specific namespace
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --node mini-arm-14 --namespace orka-test

# Deploy in a specific namespace
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --namespace orka-test

# Deploy with flexible node affinity
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=false

# Deploy with strict node affinity
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --tag jenkins-builds --tag-required=true

# Deploy using the most-allocated scheduler
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --scheduler most-allocated
```

**Examples - Advanced Deployments:**

```bash theme={null}
# Deploy with disabled VNC
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --disable-vnc

# Deploy with custom metadata
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --metadata 'foo=1,baz=https://example.com'

# Deploy with a bootstrap script that runs on first boot (Orka 4.0 or later)
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --userdata ./bootstrap.sh

# Deploy with custom port mapping (9000 to 4000 over TCP, 9001 to 4001 over UDP)
orka vm deploy -i ghcr.io/macstadium/orka-images/tahoe:latest --ports 9000:4000,9001:4001/udp
```

**Examples - VM Configuration Deployments:**

```bash theme={null}
# Deploy from existing VM config with random name
orka vm deploy --config my-vm-config

# Deploy from existing VM config with specified name
orka vm deploy my-vm --config my-vm-config

# Deploy from VM config and override CPU and memory
orka vm deploy --config my-vm-config -c 6 --memory 16
```

> **Intel-only options (Orka 3.6 and earlier)**
>
> These options apply only to Intel-based (amd64) VMs on Orka 3.6 and earlier, and some are mutually exclusive. They were removed in Orka 4.0, which supports Apple silicon only.
>
> ```bash theme={null}
> --disable-net-boost          (Optional) (Intel-only) Disable network boost
> -g, --gpu                    (Optional) (Intel-only) Enable GPU passthrough
> --iso string                 (Optional) (Intel-only) ISO name
> --legacy-io                  (Optional) (Intel-only) Enable legacy IO, for High Sierra and Mojave VMs
> --system-serial string       (Optional) (Intel-only) Custom serial number
> ```
>
> ```bash theme={null}
> # (Intel-only) Deploy with ISO for fresh macOS install
> orka3 vm deploy -i emptydisk.img --iso ventura.iso
>
> # (Intel-only) Deploy with custom serial number
> orka3 vm deploy -i 90gbventurassh.img --system-serial A00BC123D4
>
> # (Intel-only) Deploy with GPU passthrough
> orka3 vm deploy -i 90gbventurassh.img --gpu=true --disable-vnc
>
> # (Intel-only) Deploy with disabled network boost
> orka3 vm deploy -i 90gbventurassh.img --disable-net-boost
> ```

## Listing VMs

### orka vm list

Show basic or extended information about the specified VM(s).

The extended table (`--output wide`) includes the `USERDATA-PHASE` column for VMs deployed with `--userdata`: `pending`, `success`, `failed`, `skipped`, or `timeout`. The column is empty for VMs without User Data. See [Bootstrap VMs with User Data](https://docs.macstadium.com/orka/orka-resources/userdata.md#check-the-script-status).

**Syntax:**

```bash theme={null}
orka vm list [VM_NAME_1 [VM_NAME_2 ...]] [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

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

**Examples:**

```bash theme={null}
# List all VMs in the 'orka-default' namespace
orka vm list

# List all VMs (extended table)
orka vm list --output wide

# List all VMs in a specific namespace
orka vm list --namespace orka-test

# List all VMs in a specific namespace (extended table)
orka vm list --namespace orka-test --output wide

# Show basic information about a specific VM
orka vm list small-ventura-vm

# Show detailed information about a specific VM
orka vm list small-ventura-vm --output wide

# Show information about multiple VMs
orka vm list small-ventura-vm small-sonoma-vm

# Print information in JSON format
orka vm list --output json
```

## Deleting VMs

### orka vm delete

Delete the specified VMs. This frees up the respective resources and ports on the respective Orka node.

> [!WARNING]
>
> This operation cannot be undone. You will not be able to restore any unsaved or uncommitted data from the VM.

**Syntax:**

```bash theme={null}
orka vm delete VM_NAME [VM_NAME_2 ...] [--namespace CURRENT_VM_NAMESPACE] [flags]
```

**Options:**

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

**Examples:**

```bash theme={null}
# Delete a VM from the 'orka-default' namespace
orka vm delete small-ventura-vm

# Delete VMs from a specific namespace
orka vm delete small-ventura-vm small-ventura-arm-vm --namespace orka-test
```


## Related topics

- [Orka CLI command quick reference](https://docs.macstadium.com/orka/orka-cli-reference/command-quick-reference.md)
- [Orka image caching for faster VM deployments](https://docs.macstadium.com/orka/orka-resources/image-caching.md)
- [Orka Anywhere On-Prem: Troubleshooting VM Deployments](https://docs.macstadium.com/orka/orka-on-aws-and-on-prem/orka-on-prem-troubleshooting.md)
- [Cluster Configurations](https://docs.macstadium.com/orka/orka-resources/cluster-configurations.md)
- [Advanced configuration](https://docs.macstadium.com/remote-desktop-vdi/configuration/advanced-configuration.md)


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