Orka Engine 3.0 CLI Reference Guide
About
Orka Engine provides macOS virtualization via Command Line Interface (CLI) on individual hosts without complex orchestration layers. It can automate the deployment and management of VMs on macOS servers within a data center, supporting the ability to run VMs based on different images.
Overview
The Orka Engine CLI has 2 commands, and both of those commands have subcommands.
Command | Command |
---|---|
orka-engine vm | orka-engine image |
Subcommands | Subcommands |
orka-engine vm run | orka-engine image push |
orka-engine vm list | orka-engine image pull |
orka-engine vm list | orka-engine image list |
orka-engine vm start | orka-engine image copy |
orka-engine vm clone | orka-engine image delete |
orka-engine vm save | orka-engine image --help |
orka-engine vm edit | - |
orka-engine vm --help | - |
NOTE
To see help text for any command or subcommand, run:
orka-engine [command] [subcommand] --help
orka-engine vm
orka-engine vm
Overview
Commands for managing and interacting with Orka Virtual Machines
Usage
vm
Options
--version Show the version.
-h, --help Show help information.
Subcommands
subcommand | meaning |
---|---|
run | Run a virtual machine from an image or IPSW file |
list | Show detailed information for VMs |
delete | Delete a stopped VM with the provided |
start | Starts a VM |
clone | Clone a VM with the provided |
save | Save an image from a virtual machine |
edit | Edit the saved runtime configuration values for a VM |
orka-engine vm run
orka-engine vm run <vm name>
Overview
- Run a virtual machine from an image or IPSW file
- Run a virtual machine from an existing local or remote image, or install macOS from an IPSW restore file to create and run a new virtual machine.
- If a remote image is not cached in the local image store, the image will first be pulled.
- A remote image should be explicitly pulled with 'orka-engine image pull' to fetch latest changes.
- An IPSW restore file is used to install macOS in a new virtual machine.
- If not present locally, the IPSW file will first be downloaded.
- After the installation process has completed the virtual machine will be booted.
Either an image or an IPSW must be provided to run a VM.
orka-engine vm run <vm-name> --image <image> [<options>] orka-engine vm run <vm-name> --ipsw <ipsw> [--disk-size <disk-size>] [<options>]
Options
option | meaning |
---|---|
-i, --image | The name of a local image saved from an existing virtual machine, or path for a remote image stored in an OCI-compatible registry. For example, 'sonoma' or 'registry.io/organization/namespace/sonoma:latest'. |
--ipsw | The local filesystem path to an IPSW restore file, or 'latest' to fetch the latest available from Apple's servers. |
-c, --cpu | The number of CPU cores for the VM. (default: 2) |
-m, --memory | The number of megabytes of memory for the VM. (default: 4096) |
--disk-size | The size of the VM disk in gibibytes. Applicable only when the source is an IPSW file. (default: 40) |
--vnc-port | The VNC port of the VM. If not provided, the VNC console is disabled. |
--mac-address | MAC address of the VM. If not provided, defaults to a randomly generated value. Must be of the form: ab: cd: ef: 01:23:45 |
--metadata | Base64 encoded string in the following format: {"items":[{"key": "", "value": ""}]} |
--display-width | Graphical console window display width in pixels. |
--display-height | Graphical console window display height in pixels. |
--display-dpi | Graphical console display density in pixels. |
--enable-dynamic-resolution/--disable-dynamic-resolution | Automatically adjusts the display size to fit the window. (Requires macOS 14.0+) |
--disable-graphical-console | A graphical console is shown for the VM in a UI window by default. When running headless VMs intended only for remote access, this should be disabled. |
--recovery | Boot the VM in recovery mode. |
--mounts | Specify mount points as : |
--clean-cache | Free disk space if needed before running a VM by removing images from the cache. |
--version | Show the version. |
-h, --help | Show help information. |
Examples
#install latest version of macOS
orka-engine vm run --ipsw latest --disk-size 90
# run from remote image
orka-engine vm run --image GitHub
# run from local image
orka-engine vm run --image sonoma
# run headless
orka-engine vm run --image sonoma --disable-graphical-console --vnc-port 6000 --mac-address
be:d0:74:b4:bb:64
# pass custom metadata
orka-engine vm run --image sonoma --metadata
eyJpdGVtcyI6W3sia2V5IjogIm15S2V5IiwgInZhbHVlIjogIm15VmFsdWUifV19Cg==
# install from local IPSW file
orka-engine vm run --ipsw ~/Downloads/UniversalMac_14.4.1_23E224_Restore.ipsw
orka-engine vm list
orka-engine vm list
Overview
- Show detailed information for VMs.
- Displays VM configuration data for specified VMs or all VMs if none are specified.
- If VM names are provided, displays information only for those VMs.
- If no VM names are provided, lists all VMs.
- If '--output' is not set, prints the information in a table format with a limited set of values.
- Setting the output format to 'wide' or 'json' will provide all available values.
Usage
orka-engine vm list [<vm-names> ...] [--output <output>]
Arguments
The names of the VMs (optional).
Options
option | meaning |
---|---|
-o, --output | If set, changes the output format of the printed information. (values: table, json, wide; default: table) |
--version | Show the version. |
-h, --help | Show help information. |
orka-engine vm delete
orka-engine vm delete <vm-name>
Overview
Delete stopped VMs with the provided space-separated names
This operation cannot be undone. Data from the VMs cannot be restored.
Usage
orka-engine vm delete ...
Arguments
The names of the stopped VMs to delete
Options
option | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information. |
orka-engine vm start
orka-engine vm start <vm-name>
Overview
Starts a VM
Usage
orka-engine vm start []
Arguments
The name of the VM.
Options
option | meaning |
---|---|
-c, --cpu | The number of CPU cores for the VM. |
-m, --memory | The number of megabytes of memory for the VM. |
--vnc-port | The VNC port of the VM. If not provided, the VNC console is disabled. |
--mac-address | MAC address of the VM. If not provided, defaults to a randomly generated value. Must be of the form: ab: cd: ef: 01:23:45 |
--metadata | Base64 encoded string in the following format: {"items":[{"key": "", "value": ""}]} |
--display-width | Graphical console window display width in pixels. |
--display-height | Graphical console window display height in pixels. |
--display-dpi | Graphical console display density in pixels. |
--enable-dynamic-resolution/--disable-dynamic-resolution | Automatically adjusts the display size to fit the window. (Requires macOS 14.0+) |
--disable-graphical-console | A graphical console is shown for the VM in a UI window by default. When running headless VMs intended only for remote access, this should be disabled. |
--recovery | Boot the VM in recovery mode. |
--mounts | Specify mount points as : |
--version | Show the version. |
-h, --help | Show help information. |
orka-engine vm clone
orka-engine vm clone <source-vm-name>
Overview
Clone a VM with the provided
Usage
orka-engine vm clone
Arguments
The name of the VM to clone
The name of the cloned VM
Options
option | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information. |
orka-engine vm start
orka-engine vm start <vm-name>
Overview
Starts a VM
Usage
orka-engine vm start []
Arguments
The name of the VM.
Options
option | meaning |
---|---|
-c, --cpu | The number of CPU cores for the VM. |
-m, --memory | The number of megabytes of memory for the VM. |
--vnc-port | The VNC port of the VM. If not provided, the VNC console is disabled. |
--mac-address | MAC address of the VM. If not provided, defaults to a randomly generated value. Must be of the form: ab: cd: ef: 01:23:45 |
--metadata | Base64 encoded string in the following format: {"items":[{"key": "", "value": ""}]} |
--display-width | Graphical console window display width in pixels. |
--display-height | Graphical console window display height in pixels. |
--display-dpi | Graphical console display density in pixels. |
--enable-dynamic-resolution/--disable-dynamic-resolution | Automatically adjusts the display size to fit the window. (Requires macOS 14.0+) |
--disable-graphical-console | A graphical console is shown for the VM in a UI window by default. When running headless VMs intended only for remote access, this should be disabled. |
--recovery | Boot the VM in recovery mode. |
--mounts | Specify mount points as : |
--version | Show the version. |
orka-engine vm clone
orka-engine vm clone <source-vm-name>
Overview
Clone a VM with the provided
Usage
orka-engine vm clone
Arguments
The name of the VM to clone
The name of the cloned VM
Options
option | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information. |
orka-engine vm save
orka-engine vm save <source-vm-name>
Overview
- Save an image from a virtual machine
- Save a new image from an existing virtual machine to the local image store.
- The image name must match the following regular expression: [a-z0-9]+((.|_|__|-+)[a-z0-9]+)*
Usage
orka-engine vm save
Arguments
The name of the VM.
The name of the image.
Options
option | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information. |
orka-engine vm edit
orka-engine vm edit <source-vm-name>
Overview
Edit the saved runtime configuration values for a VM.
Usage
orka-engine vm edit [--cpu ] [--memory ] [--vnc-port ] [--mac-address ] [--metadata ] [--display-width ] [--display-height ] [--display-dpi ] [--enable-dynamic-resolution] [--disable-dynamic-resolution]
Arguments
The name of the VM.
Options
option | meaning |
---|---|
-c, --cpu | The number of CPU cores for the VM. |
-m, --memory | The number of megabytes of memory for the VM. |
--vnc-port | The VNC port of the VM. If not provided, the VNC console is disabled. |
--mac-address | MAC address of the VM. If not provided, defaults to a randomly generated value. Must be of the form: ab: cd: ef: 01:23:45 |
--metadata | Base64 encoded string in the following format: {"items":[{"key": "", "value": ""}]} |
--display-width | Graphical console window display width in pixels. |
--display-height | Graphical console window display height in pixels. |
--display-dpi | Graphical console display density in pixels. |
--enable-dynamic-resolution/--disable-dynamic-resolution | Automatically adjusts the display size to fit the window. (Requires macOS 14.0+) |
--disable-graphical-console | A graphical console is shown for the VM in a UI window by default. When running headless VMs intended only for remote access, this should be disabled. |
--recovery | Boot the VM in recovery mode. |
--mounts | Specify mount points as : |
--version | Show the version. |
orka-engine vm help
orka-engine vm --help
Overview
Commands for managing and interacting with Orka Virtual Machines
Usage
orka-engine vm
Options
--version Show the version.
-h, --help Show help information.
Subcommands
subcommand | meaning |
---|---|
run | Run a virtual machine from an image or IPSW file |
list | Show detailed information for VMs |
delete | Delete a stopped VM with the provided |
start | Starts a VM |
clone | Clone a VM with the provided |
save | Save an image from a virtual machine |
edit | Edit the saved runtime configuration values for a VM |
orka-engine image
orka-engine image
Overview
Commands for managing Orka images.
Usage
orka-engine image
Options
--version Show the version.
-h, --help Show help information.
Subcommands
subcommand | meaning |
---|---|
push | Upload an image to a registry |
pull | Download an image from a registry |
list | Show information for all of the images |
copy | Copy image to new location |
delete | Delete an image |
orka-engine image push
orka-engine image push <local name>
Overview
Upload an image to a registry
Usage
orka-engine image push [--archive] [--insecure] [--username ] [--password ]
Arguments
Image bundle name on local disk. For example, 90gbventurassh. The local name also acts as the path where the image will be stored, by default being relative to the configured base directory. If the local name is an absolute path to a location on disk, then it will be treated as an absolute path and ignore the base directory configuration.
Remote image name and reference. The expected format is /:. The reference is either a tag or the manifest digest. The default. reference is 'latest'. For example, 0123456789.dkr.ecr.us-east-1.amazonaws.com/90gb-ventura-ssh:latest
Options
subcommand | meaning |
---|---|
--archive | (Legacy) Use Apple Archive instead of standard compression. For backwards compatibility purposes only. |
--insecure | Use HTTP instead of HTTPS for registry requests. |
-u, --username | Username for registry authentication. |
-p, --password | Password for registry authentication. |
--version | Show the version. |
-h, --help | Show help information. |
orka-engine image pull
orka-engine image pull <remote name>
Overview
Download an image from a registry
Usage
orka-engine image pull [--insecure] [--username ] [--password ] [] [--clean-cache]
Arguments
Argument | meaning |
---|---|
Remote image name and reference. The expected format is /: The reference is either a tag or the manifest digest. The default reference is 'latest'. For example, 0123456789.dkr.ecr.us-east-1.amazonaws.com/90gb-ventura-ssh:latest | |
Image bundle name on local disk. For example, 90gbventurassh The local name also acts as the path where the image will be stored, by default being relative to the configured base directory. If the local name is an absolute path to a location on disk, then it will be treated as an absolute path and ignore the base directory configuration. If not provided, the local name will match the remote name. |
Options
subcommand | meaning |
---|---|
--insecure | Use HTTP instead of HTTPS for registry requests. |
-u, --username | Username for registry authentication. |
-p, --password | Password for registry authentication. |
--clean-cache | Free disk space if needed before pulling an image by removing images from the cache. |
--version | Show the version. |
-h, --help | Show help information. |
orka-engine image list
orka-engine image list <remote name>
Overview
Show information for all of the images.
If '--output' is not set, prints the information in a table format.
Usage
orka-engine image list [--output ]
Options
options | meaning |
---|---|
-o, --output | If set, changes the output format of the printed information. (values: table, json, wide; default: table) |
--version | Show the version. |
-h, --help | Show help information. |
orka-engine image copy
orka-engine image copy <source-image>
Overview
Copy image to new location
Usage
orka-engine image copy
Arguments
Argument | meaning |
---|---|
The URI of the image to copy. If a tag has not been provided, we assume "latest". | |
The destination name of the image. A tag of "latest" will be appended if a tag is omitted. |
Options
options | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information. |
orka-engine image delete
orka-engine image delete <source-image>
Overview
Delete an image.
Usage
orka-engine image delete
Arguments
Argument | meaning |
---|---|
The destination name of the image. A tag of "latest" will be appended if a tag is omitted. |
Options
options | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information. |
orka-engine image help
orka-engine image --help
Overview
Commands for managing Orka images
Usage
orka-engine image
Options
options | meaning |
---|---|
--version | Show the version. |
-h, --help | Show help information |
Subcommands
subcommand | meaning |
---|---|
push | Upload an image to a registry |
pull | Download an image from a registry |
list | Show information for all of the images |
copy | Copy image to new location |
delete | Delete an image |
Updated 23 days ago