> ## 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`.
### orka3 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}
orka3 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-net-boost (Optional) (Intel-only) Disables network performance boost
--disable-vnc (Optional) Disable VNC (ensure SSH/Screen Sharing is enabled)
-g, --gpu (Optional) (Intel-only) Enable GPU passthrough
-h, --help Display help for create
-i, --image string (Required) Base image (local or OCI)
--iso string (Optional) (Intel-only) ISO name to attach
-m, --memory float (Optional) RAM in gigabytes
--scheduler string (Optional) Scheduler: 'default' or 'most-allocated'
--system-serial string (Optional) (Intel-only) Custom serial number
--tag string (Optional) Node affinity tag
--tag-required (Optional) Require tagged nodes for deployment
```
**Examples:**
```bash theme={null}
# Create a template for an Intel-based VM
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --cpu 6
# Create a template for an Apple silicon VM using an OCI image
orka3 vmc create small-arm-vm -i ghcr.io/my-org/orka-images/orka-arm:latest --cpu 4
# Create a template with 5GB RAM
orka3 vmc create medium-ventura-arm-vm --image 90gbventurassh.orkasi --memory 5
# (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
# Create a template with flexible node affinity
orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --tag jenkins-builds --tag-required=false
# Create a template with strict node affinity
orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --tag jenkins-builds --tag-required=true
# Create a template that uses the most-allocated scheduler
orka3 vmc create medium-ventura-vm --image 90gbventurassh.orkasi --scheduler most-allocated
# (Intel-only) Create a template with GPU passthrough
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --gpu=true --disable-vnc
# Create a template with disabled VNC
orka3 vmc create medium-ventura-vm --image 90gbventurassh.img --disable-vnc
```
### orka3 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}
orka3 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
orka3 vmc list
# List extended information
orka3 vmc list --output wide
# Show basic information about a specific VM configuration
orka3 vmc list small-ventura-vm
# Show extended information about a specific VM configuration
orka3 vmc list small-ventura-vm --output wide
# Show information about multiple VM configurations
orka3 vmc list small-monterey small-ventura
# Return output as JSON
orka3 vmc list --output json
```
### orka3 vm-config delete
Delete the specified VM configurations (templates).
**Syntax:**
```bash theme={null}
orka3 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
orka3 vmc delete small-ventura-arm-vm
# Delete multiple VM configurations
orka3 vmc delete medium-ventura-vm medium-ventura-arm-vm
```
## Deploying VMs
### orka3 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
**Note:** Some settings are Intel-only (amd64 architecture) and some settings might be mutually exclusive.
**Syntax:**
```bash theme={null}
orka3 vm deploy [VM_NAME] --image IMAGE_NAME [flags]
orka3 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-net-boost (Optional) (Intel-only) Disable network boost
--disable-vnc (Optional) Disable VNC
--generate-name (Optional) Generate unique name with suffix
-g, --gpu (Optional) (Intel-only) Enable GPU passthrough
-h, --help Display help for deploy
-i, --image string (Required) Base image (local or OCI)
--iso string (Optional) (Intel-only) ISO name
-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)
--scheduler string (Optional) Scheduler: 'default' or 'most-allocated'
--system-serial string (Optional) (Intel-only) Custom serial number
--tag string (Optional) Node affinity tag
--tag-required (Optional) Require tagged nodes
--timeout int (Optional) Deployment timeout in minutes (default 10)
-n, --namespace string (Optional) Namespace scope (default "orka-default")
```
**Examples - Basic Deployments:**
```bash theme={null}
# Deploy a VM from a local Orka image
orka3 vm deploy -i 90gbventurassh.orkasi
# Deploy a VM from an OCI image
orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest
# Deploy with specified name, image, and CPU
orka3 vm deploy small-ventura-vm -i 90gbventurassh.orkasi -c 4
# Deploy with unique name generation
orka3 vm deploy small-ventura-vm -i 90gbventurassh.orkasi --generate-name
# Deploy with specified memory and random name
orka3 vm deploy -i 90gbventurassh.orkasi -m 10
# Deploy and display extended information
orka3 vm deploy -i 90gbventurassh.orkasi --output wide
# Deploy with custom timeout
orka3 vm deploy -i 90gbventurassh.orkasi --timeout 1
```
**Examples - Targeted Deployments:**
```bash theme={null}
# Deploy on a selected node
orka3 vm deploy -i 90gbventurassh.orkasi --node mini-arm-14
# Deploy on a selected node in a specific namespace
orka3 vm deploy -i 90gbventurassh.orkasi --node mini-arm-14 --namespace orka-test
# Deploy in a specific namespace
orka3 vm deploy -i 90gbventurassh.orkasi --namespace orka-test
# Deploy with flexible node affinity
orka3 vm deploy -i 90gbventurassh.orkasi --tag jenkins-builds --tag-required=false
# Deploy with strict node affinity
orka3 vm deploy -i 90gbventurassh.orkasi --tag jenkins-builds --tag-required=true
# Deploy using the most-allocated scheduler
orka3 vm deploy -i 90gbventurassh.orkasi --scheduler most-allocated
```
**Examples - Advanced Deployments:**
```bash theme={null}
# Deploy with disabled VNC
orka3 vm deploy -i 90gbventurassh.img --disable-vnc
# Deploy with custom metadata
orka3 vm deploy -i 90gbventurassh.img --metadata 'foo=1,baz=https://example.com'
# Deploy with custom port mapping
orka3 vm deploy -i 90gbventurassh.img --ports 9000:4000,9001:4001
```
**Examples - Intel-Only Deployments:**
```bash theme={null}
# Deploy with ISO for fresh macOS install
orka3 vm deploy -i emptydisk.img --iso ventura.iso
# Deploy with custom serial number
orka3 vm deploy -i 90gbventurassh.img --system-serial A00BC123D4
# Deploy with GPU passthrough
orka3 vm deploy -i 90gbventurassh.img --gpu=true --disable-vnc
# Deploy with disabled network boost
orka3 vm deploy -i 90gbmontereyssh.img --disable-net-boost
```
**Examples - VM Configuration Deployments:**
```bash theme={null}
# Deploy from existing VM config with random name
orka3 vm deploy --config small-ventura-config
# Deploy from existing VM config with specified name
orka3 vm deploy small-ventura-vm --config small-ventura-config
# Deploy from VM config and override CPU and memory
orka3 vm deploy --config small-ventura-config -c 6 --memory 16
```
## Listing VMs
### orka3 vm list
Show basic or extended information about the specified VM(s).
Stopped or suspended VMs appear as 'Running' when listed. Do not rely on the displayed status to confirm a VM is active before scheduling work against it.
**Syntax:**
```bash theme={null}
orka3 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
orka3 vm list
# List all VMs (extended table)
orka3 vm list --output wide
# List all VMs in a specific namespace
orka3 vm list --namespace orka-test
# List all VMs in a specific namespace (extended table)
orka3 vm list --namespace orka-test --output wide
# Show basic information about a specific VM
orka3 vm list small-ventura-vm
# Show detailed information about a specific VM
orka3 vm list small-ventura-vm --output wide
# Show information about multiple VMs
orka3 vm list small-ventura-vm small-monterey-vm
# Print information in JSON format
orka3 vm list --output json
```
## Deleting VMs
### orka3 vm delete
Delete the specified VMs. This frees up the respective resources and ports on the respective Orka node.
This operation cannot be undone. You will not be able to restore any unsaved or uncommitted data from the VM.
**Syntax:**
```bash theme={null}
orka3 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
orka3 vm delete small-ventura-vm
# Delete VMs from a specific namespace
orka3 vm delete small-ventura-vm small-ventura-arm-vm --namespace orka-test
```