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

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.

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

About

Overview

🗒️NOTE

orka-engine vm

Overview

Usage

Options

Subcommands

orka-engine vm run

Overview

Options

Examples

orka-engine vm list

Overview

Usage

Arguments

Options

orka-engine vm delete

Overview

Usage

Arguments

Options

orka-engine vm start

Overview

Usage

Arguments

Options

orka-engine vm clone

Overview

Usage

Arguments

Options

orka-engine vm start

Overview

Usage

Arguments

Options

orka-engine vm clone

Overview

Usage

Arguments

Options

orka-engine vm save

Overview

Usage

Arguments

Options

orka-engine vm edit

Overview

Usage

Arguments

Options

orka-engine vm help

Overview

Usage

Options

Subcommands

orka-engine image

Overview

Usage

Options

Subcommands

orka-engine image push

Overview

Usage

Arguments

Options

orka-engine image pull

Overview

Usage

Arguments

Options

orka-engine image list

Overview

Usage

Options

orka-engine image copy

Overview

Usage

Arguments

🗒️
NOTE