Command-line Reference
Anka CLI Reference
Environment Variables
By default, all anka config options are available as Environment Variables by simply converting their name to uppercase and prefixing it with ANKA_. So, default_user becomes ANKA_DEFAULT_USER and the ENV takes precedence.
Outside of the config environment variables, there are a few others you might find useful:
| Name | Description |
|---|---|
| ANKA_REGISTRY | The URL of the registry to use for anka pull/push/registry commands |
| ANKA_NETWORK_MODE | Allow setting network mode when running anka create |
| ANKA_NETWORK_CONTROLLER | Allow setting network controller when running anka create |
| ANKA_DISK_CONTROLLER | Allow setting disk controller when running anka create |
| ANKA_MACHINE_READABLE | Whether or not commands return machine readable |
| ANKA_DEBUG | Set to 1 and this will allow click scripts to output /tmp/_last* png files for debugging. |
| ANKA_START_MODE | Allow starting the VM in normal or recovery mode. Recovery mode is 2. |
| ANKA_REGISTRY_API_KEY_ID | The UAK ID to use for registry commands. |
| ANKA_REGISTRY_API_KEY | The UAK private key file location for registry commands |
| ANKA_HOSTNAME | Allows to specify VM host name on VM start |
| ANKA_BRIDGE | The name of the network bridge name to target. |
| ANKA_CREATE_VNC | Set to 0 to disable executing the VNC enable step/script in anka create. |
| ANKA_CREATE_SIP | Set to 0 to disable executing the SIP disabling step/script in anka create. |
One of the most common problems when getting started is the usage of sudo for anka commands. Anka will run for all users on a machine, but they will have isolated environments. If you create an Anka VM Template/Tag as UserA, sudo/root will not be able to see or use them. Also, the Anka Build Cloud Controller will start VMs as root, so be sure to clean up any VM Templates and Tags you have under UserA or else the disk space will become a problem. It’s suggested to just run all anka commands as root.> anka --help
usage: anka [options] <command>
Anka command line tool
options:
-j,--machine-readable Output a machine readable format (JSON)
--version Output the Anka version
commands:
list List local VM library
config Manage the CLI configuration
show Show a VM's properties
modify Modify a VM parameters
view Open VM display
run Run a command inside of a VM
create Creates a VM Template
start Start or resume a VM
stop Shut down a VM(s)
clone Clone a VM
push Push a VM to the registry
pull Pull a VM template from the registry
usb Manage USB devices
attach Attach USB device(s) to a running VM
detach Detach USB device(s) from a VM
reboot Reboot a running VM(s)
delete Delete a VM(s) and tags
registry Configure and control template registries
cp Copy files in/out of the Anka VM and host:
cp [options] <vmid>:path/inside </path/on/host>
cp [options] </path/on/host> <vmid>:[path/inside]
license Manage licenses
export Export a VM as an archive
import Import VM from an archive
List
> anka list --help
usage: list [options] [vmid...]
List local VM library
arguments:
vmid Particular VM(s) to list, all by default
options:
-r,--running Show only running VMs
-s,--stopped Show only stopped/suspended VMs
-a,--all Show all the VMs including cached ones
-f,--field <val> Specify the fields displayed for the VM
❯ anka list
+----------------------+--------------------------------------+---------------------+---------+
| name | uuid | creation_date | status |
+----------------------+--------------------------------------+---------------------+---------+
| 12.2.0-arm (vanilla) | a6f24306-2af7-45ed-9d70-3a3c1ee7f03a | Jan 6 12:34:52 2022 | stopped |
+----------------------+--------------------------------------+---------------------+---------+
| test_vm1 | 565e47ce-a9f9-4ac8-81bc-645d48473de1 | Jan 6 12:34:52 2022 | stopped |
+----------------------+--------------------------------------+---------------------+---------+
❯ anka --machine-readable list | jq
{
"status": "OK",
"body": [
{
"name": "12.2.0-arm",
"uuid": "a6f24306-2af7-45ed-9d70-3a3c1ee7f03a",
"creation_date": "2022-01-06T12:34:52Z",
"version": "vanilla",
"status": "stopped"
},
{
"name": "test_vm1",
"uuid": "565e47ce-a9f9-4ac8-81bc-645d48473de1",
"creation_date": "2022-01-06T12:34:52Z",
"status": "stopped"
}
]
}
❯ anka --machine-readable list --field name --field version | jq
{
"status": "OK",
"body": [
{
"name": "12.2.0-arm",
"version": "vanilla"
},
{
"name": "test_vm1"
}
]
}
Config
> anka config --help
usage: config [options] [param...]
Manage the CLI configuration
arguments:
param Parameter name
options:
-l,--list List parameter(s)
-r,--reset Reset parameter(s) back to default
❯ anka config
+-----------------------------+-------------------------------------------------------------------------------------------+
| addons_disk_tool | /Library/Application Support/Veertu/Anka/guestaddons/create_update_disk.sh |
+-----------------------------+-------------------------------------------------------------------------------------------+
| addons_identifier | ANKA_ADDONS_IDENTIFIER |
+-----------------------------+-------------------------------------------------------------------------------------------+
| addons_image | /Library/Application Support/Veertu/Anka/guestaddons/anka-addons-mac |
+-----------------------------+-------------------------------------------------------------------------------------------+
| addons_pkg | com.veertu.anka.guestaddons.pkg |
+-----------------------------+-------------------------------------------------------------------------------------------+
| addons_postupdate | /Library/Application Support/Veertu/Anka/guestaddons/postupdate.sh |
+-----------------------------+-------------------------------------------------------------------------------------------+
| allow_nonunique_names | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| anka_executable | /Library/Application Support/Veertu/Anka/bin/ankahv-arm64.app/Contents/MacOS/ankahv-arm64 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| anka_image_maker_executable | /Library/Application Support/Veertu/Anka/bin/anka_image |
+-----------------------------+-------------------------------------------------------------------------------------------+
| anka_viewer | /Applications/Anka.app |
+-----------------------------+-------------------------------------------------------------------------------------------+
| ankactl_executable | /Library/Application Support/Veertu/Anka/bin/ankactl |
+-----------------------------+-------------------------------------------------------------------------------------------+
| ankanet_sock | /var/run/ankanetd |
+-----------------------------+-------------------------------------------------------------------------------------------+
| ankasc_executable | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| bios_path | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| block_nocache | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| bridge_name | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| ca_bundle | /Users/nathanpierce/.anka/ca-bundle.crt |
+-----------------------------+-------------------------------------------------------------------------------------------+
| catalog_url | https://mesu.apple.com/assets/macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml |
+-----------------------------+-------------------------------------------------------------------------------------------+
| chunk_size | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| click_executable | /Library/Application Support/Veertu/Anka/bin/click |
+-----------------------------+-------------------------------------------------------------------------------------------+
| create_suspend | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| default_disk | 137438953472 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| default_format | 1 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| default_nvcpu | 4 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| default_passwd | admin |
+-----------------------------+-------------------------------------------------------------------------------------------+
| default_ram | 4294967296 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| default_user | anka |
+-----------------------------+-------------------------------------------------------------------------------------------+
| delete_logs | 1 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| end_address | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| exit_delay | 10 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| fvutil_executable | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| img_lib_dir | /Users/nathanpierce/Library/Application Support/Veertu/Anka/img_lib |
+-----------------------------+-------------------------------------------------------------------------------------------+
| img_path | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| implicit_mount | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| install_tool | /Library/Application Support/Veertu/Anka/bin/ankahv-arm64.app/Contents/MacOS/ankahv-arm64 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| io_threads | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| log_dir | /Users/nathanpierce/Library/Logs/Anka/ |
+-----------------------------+-------------------------------------------------------------------------------------------+
| log_file | anka.log |
+-----------------------------+-------------------------------------------------------------------------------------------+
| max_vms_allowed | 255 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| network_failure_action | 1 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| nice | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| operations_timeout | 300 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| options_api_url | https://licensing.veertu.com/prod/key/info |
+-----------------------------+-------------------------------------------------------------------------------------------+
| portfwd_base | 10000 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| process_type | Interactive |
+-----------------------------+-------------------------------------------------------------------------------------------+
| product_root | /Library/Application Support/Veertu/Anka |
+-----------------------------+-------------------------------------------------------------------------------------------+
| propagate_license | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| propagate_name | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| pull_checkout | 1 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| pull_failback | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| pull_resume | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| puller_threads | 4 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| qncpu | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| quantum | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| qvcpu | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| registry_remotes_file_path | /Users/nathanpierce/.anka/remote |
+-----------------------------+-------------------------------------------------------------------------------------------+
| shared_nat | 0 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| start_address | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| state_lib_dir | /Users/nathanpierce/Library/Application Support/Veertu/Anka/img_lib |
+-----------------------------+-------------------------------------------------------------------------------------------+
| subnet_mask | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| swap_dir | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| table_fmt | grid |
+-----------------------------+-------------------------------------------------------------------------------------------+
| tag_lib_dir | |
+-----------------------------+-------------------------------------------------------------------------------------------+
| tessdata_dir | /Library/Application Support/Veertu/Anka/tessdata |
+-----------------------------+-------------------------------------------------------------------------------------------+
| tesslang | eng |
+-----------------------------+-------------------------------------------------------------------------------------------+
| time_sync | 1 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| trim_disk | 1 |
+-----------------------------+-------------------------------------------------------------------------------------------+
| uhost_executable | /Library/Application Support/Veertu/Anka/bin/uhost |
+-----------------------------+-------------------------------------------------------------------------------------------+
| vlaunch_sock | /var/run/vlaunchd |
+-----------------------------+-------------------------------------------------------------------------------------------+
| vm_lib_dir | /Users/nathanpierce/Library/Application Support/Veertu/Anka/vm_lib |
+-----------------------------+-------------------------------------------------------------------------------------------+
| vm_lock_dir | /Users/nathanpierce/Library/Application Support/Veertu/Anka/vm_lib/.locks |
+-----------------------------+-------------------------------------------------------------------------------------------+
❯ anka config puller_threads
4
❯ anka config puller_threads 10
❯ anka config puller_threads
10
Show
> anka show --help
usage: show [options] vmid <command>
Show a VM's properties
arguments:
vmid VM identifier or name
options:
-t,--tag <val> Specify VM tag, current by default
commands:
name VM name
uuid VM UUID
description VM description
tag Local VM tags
cpu vCPU parameters
ram RAM size and parameters
display Display information
disk Disk information
network Network information
port Port forwarding rules
label Show assigned VM labels
❯ anka show 12.2.0-arm
+---------+--------------------------------------+
| uuid | a6f24306-2af7-45ed-9d70-3a3c1ee7f03a |
+---------+--------------------------------------+
| name | 12.2.0-arm (vanilla) |
+---------+--------------------------------------+
| created | Jan 6 12:34:52 2022 |
+---------+--------------------------------------+
| vcpu | 4 ARM |
+---------+--------------------------------------+
| ram | 4G |
+---------+--------------------------------------+
| display | 1024x768 |
+---------+--------------------------------------+
| disk | 128GiB (17.72GiB on disk) |
+---------+--------------------------------------+
| addons | 3.0.0.135.13568747 |
+---------+--------------------------------------+
| network | shared |
+---------+--------------------------------------+
| status | stopped Jan 6 18:10:17 2022 |
+---------+--------------------------------------+
❯ anka --machine-readable show 12.2.0-arm | jq
{
"status": "OK",
"body": {
"uuid": "a6f24306-2af7-45ed-9d70-3a3c1ee7f03a",
"name": "12.2.0-arm",
"version": "vanilla",
"creation_date": "2022-01-06T12:34:52Z",
"cpu_cores": 4,
"cpu_frequency": 0,
"cpu_htt": false,
"arch": 2,
"ram": "4294967296",
"ram_size": 4294967296,
"frame_buffers": 1,
"hard_drive": 137438953472,
"encrypted": false,
"image_size": 19035295744,
"addons_version": "3.0.0.135.13568747",
"stop_date": "2022-01-06T18:10:17Z",
"status": "stopped"
}
}
❯ anka --machine-readable show 12.2.0-arm --tag v2 | jq
{
"status": "OK",
"body": {
"uuid": "a6f24306-2af7-45ed-9d70-3a3c1ee7f03a",
"name": "12.2.0-arm",
"version": "v2",
"creation_date": "2022-01-14T12:18:31Z",
"cpu_cores": 4,
"cpu_frequency": 0,
"cpu_htt": false,
"arch": 2,
"ram": "4294967296",
"ram_size": 4294967296,
"frame_buffers": 1,
"hard_drive": 137438953472,
"encrypted": false,
"image_size": 19528679424,
"addons_version": "3.0.0.135.13568747",
"stop_date": "2022-01-14T17:19:08Z",
"status": "stopped"
}
}
show {name/uuid} name
> anka show 14.3.1-arm64 name --help
show {name/uuid} uuid
> anka show 14.3.1-arm64 uuid --help
show {name/uuid} description
> anka show 14.3.1-arm64 description --help
show {name/uuid} tag
> anka show 14.3.1-arm64 tag --help
usage: tag [options]
Local VM tags
options:
--current Show the currently checked out tag
show {name/uuid} cpu
> anka show 14.3.1-arm64 cpu --help
show {name/uuid} ram
> anka show 14.3.1-arm64 ram --help
show {name/uuid} display
> anka show 14.3.1-arm64 display --help
show {name/uuid} disk
> anka show 14.3.1-arm64 disk --help
usage: disk [options]
Disk information
options:
-d,--disk-index <val> Specify disk index to show
show {name/uuid} network
> anka show 14.3.1-arm64 network --help
usage: network [options]
Network information
options:
-f,--filter show network filter rules
show {name/uuid} port
> anka show 14.3.1-arm64 port --help
show {name/uuid} label
> anka show 14.3.1-arm64 label --help
usage: label [name]
Show assigned VM labels
arguments:
name Show particular label value
show {name/uuid} usb
> anka show 14.2.1 usb --help
Modify
> anka modify --help
usage: modify vmid <command>
Modify a VM parameters
arguments:
vmid Virtual machine to modify
commands:
add Add new items to a VM configuration
delete Remove items from a VM configuration
name Set new name for the VM
cpu Set number of vcpu cores and frequency
ram Set RAM size and parameters
network Modify network card settings
port Add port forwarding rule
disk Modify hard drive settings
display Configure displays
label Assign labels to a VM in key/value form
modify {name/uuid} add
> anka modify 14.3.1-arm64 add --help
usage: add <command>
Add new items to a VM configuration
commands:
network Modify network card settings
disk Modify hard drive settings
port Add port forwarding rule
label Assign labels to a VM in key/value form
modify {name/uuid} add network
> anka modify 14.3.1-arm64 add network --help
usage: network-card,network [options]
Modify network card settings
options:
-t,--mode <val> network mode: shared/host/bridge/disconnected
-b,--bridge <val> host interface name to bridge with in the bridge mode, or "auto"
-m,--mac <val> specify fixed MAC address, or "auto"
-v,--vlan <val> assign VLAN ID, 0 to deassign
-c,--controller <val> set controller: anet, virtio-net
-f,--filter <val> filtering rules file to inject on VM start, or embed in VM config (with '-f- < rules.txt'), or use 'off' to disable
modify {name/uuid} add disk
> anka modify 14.3.1-arm64 add disk --help
usage: hard-drive,disk [options]
Modify hard drive settings
options:
-c,--controller <val> set controller: sata/virtio-blk
-s,--size <val> set disk size (supported suffixes: T|G|M|K)
-f,--file <val> assign external image or device
--ro mark the image as read-only for the VM
--rw mark the image as writable (default) for the VM
modify {name/uuid} add port
> anka modify 14.3.1-arm64 add port --help
usage: port-forwarding,port [options] name [rule]
Add port forwarding rule
arguments:
name Rule name
rule Port forwarding rule: guest-port[:host-ip][:host-port]
options:
-g,--guest-port <val> The port inside of the VM that the host-port connects to
-p,--host-port <val> The host port to listen on (assigns dynamically if not specified)
-l,--host-ip <val> Listen address (defaults to any)
-d,--delete Delete the rule
--set-name <val> Rename the rule
modify {name/uuid} add label
> anka modify 14.3.1-arm64 add label --help
usage: label [options] [name] [value]
Assign labels to a VM in key/value form
arguments:
name Label name
value Value of the label
options:
-d,--delete Delete the label(s)
--set-name Rename the label to the value
modify {name/uuid} delete
> anka modify 14.3.1-arm64 delete --help
usage: delete <command>
Remove items from a VM configuration
commands:
network Remove network card
disk Remove disk
port Remove port forwarding rule
label Remove labels
modify {name/uuid} delete network
> anka modify 14.3.1-arm64 delete network --help
modify {name/uuid} delete disk
> anka modify 14.3.1-arm64 delete disk --help
usage: hard-drive,disk index
Remove disk
arguments:
index Index of the disk to remove
modify {name/uuid} delete port
> anka modify 14.3.1-arm64 delete port --help
usage: port-forwarding,port [options] [rule...]
Remove port forwarding rule
arguments:
rule Name of the port forwarding rule
options:
-a,--all Remove all the port fowarding rules
modify {name/uuid} delete label
> anka modify 14.3.1-arm64 delete label --help
usage: label [options] [label...]
Remove labels
arguments:
label Labels to delete
options:
-a,--all Delete all the labels assigned
modify {name/uuid} name
> anka modify 14.3.1-arm64 name --help
usage: name name
Set new name for the VM
arguments:
name New name
modify {name/uuid} cpu
> anka modify 14.3.1-arm64 cpu --help
usage: cpu [options] [vcpu]
Set number of vcpu cores and frequency
arguments:
vcpu Number of vcpu cores
options:
-c,--cores <val> Number of vcpu cores
-f,--frequency <val> Set the base vcpu frequency (Hz)
❯ anka show 12.6 cpu
+-------+---+
| cores | 4 |
+-------+---+
❯ anka modify 12.6 cpu 5
❯ anka show 12.6 cpu
+-------+---+
| cores | 5 |
+-------+---+
modify {name/uuid} ram
> anka modify 14.3.1-arm64 ram --help
usage: ram [size]
Set RAM size and parameters
arguments:
size Size of RAM (supported suffixes: T|G|M|K)
❯ anka show 12.6 ram
+------+------+
| size | 4GiB |
+------+------+
❯ anka modify 12.6 ram 6G
❯ anka show 12.6 ram
+------+------+
| size | 6GiB |
+------+------+
modify {name/uuid} network
> anka modify 14.3.1-arm64 network --help
usage: network [options]
Modify network card settings
options:
-t,--mode <val> network mode: shared/host/bridge/disconnected
-b,--bridge <val> host interface name to bridge with in the bridge mode, or "auto"
-m,--mac <val> specify fixed MAC address, or "auto"
-v,--vlan <val> assign VLAN ID, 0 to deassign
-c,--controller <val> set controller: anet, virtio-net
-f,--filter <val> filtering rules file to inject on VM start, or embed in VM config (with '-f- < rules.txt'), or use 'off' to disable
| Type | Description |
|---|---|
shared | The default network type operating as NAT + DHCP. Every VM after the start/resume gets an IP address assigned by the internal DHCP server in range 192.168.64.2 - 192.168.64.254. Programs inside a VM can access external networks (outside the host) and the internet directly. Also, other VMs on the host are also accessible. |
host | Not currently supported. |
bridge | The Bridged type will cause the VM to show in the network as an individual device and receive a unique IP separate from the host.An ENV is available to set the interface name: When using the bridge, port-forwarding is not necessary as the VM will receive a unique IP that will be accessible directly to all other devices on the network. By default, DHCP will not see your VM’s MAC address. You’ll need to enable |
disconnected | The VM will have a disconnected network cable. |
nat | Experimental network mode for Apple Silicon/ARM, allowing ~10x the speed compared to the shared mode. Does not support VM to Host isolation or ARP Spoofing prevention. |
❯ anka --machine-readable show 13.1 network | jq '.body'
{
"mode": "shared",
"controller": "virtio-net",
"port_forwarding_rules": [
{
"name": "ssh",
"protocol": "tcp",
"guest_port": 22
}
]
}
❯ anka modify 13.1 network --mode bridge
❯ anka --machine-readable show 13.1 network | jq '.body.mode'
"bridge"
modify {name/uuid} port
> anka modify 14.3.1-arm64 port --help
usage: port [options] name [rule]
Add port forwarding rule
arguments:
name Rule name
rule Port forwarding rule: guest-port[:host-ip][:host-port]
options:
-g,--guest-port <val> The port inside of the VM that the host-port connects to
-p,--host-port <val> The host port to listen on (assigns dynamically if not specified)
-l,--host-ip <val> Listen address (defaults to any)
-d,--delete Delete the rule
--set-name <val> Rename the rule
We do not recommend setting--host-port, as it will cause collisions if two VMs attempt to use the same port. If no--host-portis specified, we will dynamically assign them starting from 10000 and incrementing (10001, 10002, etc) depending on if there are other VMs running and consuming ports from the range already.
❯ anka modify 12.6 port --help
usage: port [options] name [rule]
Add port forwarding rule
arguments:
name Rule name
rule Port forwarding rule: guest-port[:host-ip][:host-port]
options:
-g,--guest-port <val> The port inside of the VM that the host-port connects to
-p,--host-port <val> The host port to listen on (assigns dynamically if not specified)
-l,--host-ip <val> Listen address (defaults to any)
-d,--delete Delete the rule
--set-name <val> Rename the rule
❯ anka modify 12.6 port vnc 5900
❯ anka modify 12.6 port ssh 22:0.0.0.0
❯ anka start 12.6
❯ anka show 12.6 network
. . .
port_forwarding_rules:
+------+----------+------------+-----------+
| name | protocol | guest_port | host_port |
+------+----------+------------+-----------+
| ssh | tcp | 22 | 10000 |
| vnc | tcp | 5900 | 10001 |
+------+----------+------------+-----------+
❯ ssh anka@localhost -p 10000
(anka@localhost) Password:
Last login: Fri Oct 14 06:37:54 2022
anka@Ankas-Virtual-Machine ~ %
modify {name/uuid} disk
> anka modify 14.3.1-arm64 disk --help
usage: disk [options]
Modify hard drive settings
options:
-c,--controller <val> set controller: sata/virtio-blk
-s,--size <val> set disk size (supported suffixes: T|G|M|K)
-f,--file <val> assign external image or device
--ro mark the image as read-only for the VM
--rw mark the image as writable (default) for the VM
Post-modify, you need to tell disk utility to modify the VM’s disk to consume the new free space: anka run {vmNameOrUUID} sudo diskutil apfs resizeContainer disk0s2 0It’s currently impossible to downsize a VM’s hard-drive. We suggest creating your initial VM Template with a smaller amount of available disk and then increase in subsequent Tags.
❯ anka show 12.6 disk size
128GiB
❯ anka modify 12.6 disk -s 200G
❯ anka run 12.6 bash -c "df -h"
Filesystem Size Used Avail Capacity iused ifree %iused Mounted on
/dev/disk2s1s1 123Gi 14Gi 106Gi 12% 502068 1106561040 0% /
❯ anka run 12.6 bash -c "diskutil apfs resizeContainer disk0s2 0"
Started APFS operation
Aligning grow delta to 77,309,411,328 bytes and targeting a new physical store size of 208,855,367,680 bytes
Determined the maximum size for the targeted physical store of this APFS Container to be 208,855,370,752 bytes
Resizing APFS Container designated by APFS Container Reference disk2
The specific APFS Physical Store being resized is disk0s2
Verifying storage system
Using live mode
Performing fsck_apfs -n -x -l /dev/disk0s2
Checking the container superblock
. . .
Verifying volume object map space
The volume /dev/rdisk2s6 appears to be OK
Verifying allocated space
The container /dev/disk0s2 appears to be OK
Storage system check exit code is 0
Growing APFS Physical Store disk0s2 from 131,545,956,352 to 208,855,367,680 bytes
Modifying partition map
Growing APFS data structures
Finished APFS operation
❯ anka run 12.6 bash -c "df -h"
Filesystem Size Used Avail Capacity iused ifree %iused Mounted on
/dev/disk2s1s1 195Gi 14Gi 177Gi 8% 502068 1860793720 0% /
modify {name/uuid} display
> anka modify 14.3.1-arm64 display --help
usage: display [options]
Configure displays
options:
-n,--count <val> Configure number of displays (2 max)
--headless same as --count 0
-p,--password Deprecated, use 'anka config vnc_password' instead
--vnc <val> Configure VNC: on/off/address
--no-vnc Disable VNC access to the VM
-d,--dpi <val> Set DPI (default is 72)
-r,--resolution <val> Set resolution, e.g. 1024x768 or 'default' to reset to default
-f,--fps <val> Set refresh rate (30fps by default)
-c,--controller <val> Set video controller: fbuf/pg
--host-gpu-location <val>
Specify location of the host GPU to use, or 'any'
--host-gpu-name <val> Specify name of the host GPU to use, or 'any'
--features <val> Specify extended features flags as a bit mask
modify {name/uuid} label
> anka modify 14.3.1-arm64 label --help
usage: label [options] [name] [value]
Assign labels to a VM in key/value form
arguments:
name Label name
value Value of the label
options:
-d,--delete Delete the label(s)
--set-name Rename the label to the value
View
> anka view --help
usage: view [options] vmid
Open VM display
arguments:
vmid VM to view
options:
-d,--display <val> Specify the display(s) to view
-s,--screenshot Take PNG screenshot
--pbpaste Get the VM's pasteboard
--pbcopy Send stdin to the VM's pasteboard
--click <val> Send HID events
-o,--output <val> Specify output file for the view operations
Run
> anka run --help
usage: run [options] vmid
Run a command inside of a VM
arguments:
vmid VM name or identifier (will be started if needed)
options:
-D,-w,--workdir <val> Working directory inside the VM
-E Inherit the entire environment in non-overriding mode
-e <val> Provide an environment variable in overriding mode
-f,--env-file <val> Provide environment variables from file
-q,--quiet Suppress the stdout from the command
-b,--background Background the command inside of VM, returning inner VM PID
Note:anka runwill start the default shell Apple/macOS provides. This may be limited for your use-case and you may want to run ``anka run {vmName} bash -lcorzsh -lc` to execute with the full environment.
Shell Configuration Files / Environment
The anka run command uses the “default shell” that Apple’s API provides inside of macOS. It will NOT source any configuration by default. However, you can use bash and zsh command with anka run to source them:
❯ anka run "${VM_NAME}" bash -c "echo 'export TEST_ZSHRC=yes' >> ~/.zshrc"
anka run "${VM_NAME}" bash -c "echo 'export TEST_ZPROFILE=yes' >> ~/.zprofile"
anka run "${VM_NAME}" bash -c "echo 'export TEST_PROFILE=yes' >> ~/.profile"
anka run "${VM_NAME}" bash -c "echo 'export TEST_BASH_PROFILE=yes' >> ~/.bash_profile"
❯ anka run "${VM_NAME}" env
XPC_SERVICE_NAME=com.veertu.anka.addons.ankarun
SSH_AUTH_SOCK=/private/tmp/com.apple.launchd.y6GCwIr092/Listeners
PATH=/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin
XPC_FLAGS=0x0
LOGNAME=anka
USER=anka
HOME=/Users/anka
SHELL=/bin/bash
TMPDIR=/var/folders/01/58yvsx8s4f79plzlx2_rcvp40000gn/T/
__CF_USER_TEXT_ENCODING=0x1F5:0x0:0x0
SHLVL=1
❯ anka run "${VM_NAME}" bash -c "env | grep TEST_"
❯ anka run "${VM_NAME}" bash -ic "env | grep TEST_"
❯ anka run "${VM_NAME}" bash -lc "env | grep TEST_"
TEST_BASH_PROFILE=yes
❯ anka run "${VM_NAME}" zsh -c "env | grep TEST_"
❯ anka run "${VM_NAME}" zsh -ic "env | grep TEST_"
TEST_ZSHRC=yes
❯ anka run "${VM_NAME}" zsh -lc "env | grep TEST_"
TEST_ZPROFILE=yes
❯ anka stop "${VM_NAME}"
❯ anka run "${VM_NAME}" bash -c "env | grep TEST_"
TEST_ZPROFILE=yes
❯ anka run "${VM_NAME}" bash -ic "env | grep TEST_"
TEST_ZPROFILE=yes
❯ anka run "${VM_NAME}" bash -lc "env | grep TEST_"
TEST_ZPROFILE=yes
TEST_BASH_PROFILE=yes
❯ anka run "${VM_NAME}" zsh -c "env | grep TEST_"
TEST_ZPROFILE=yes
❯ anka run "${VM_NAME}" zsh -ic "env | grep TEST_"
TEST_ZPROFILE=yes
TEST_ZSHRC=yes
❯ anka run "${VM_NAME}" zsh -lc "env | grep TEST_"
TEST_ZPROFILE=yes
To inherit the host’s environment, use theanka run -E(existing VM variables will not be overridden by host’s variables) or-e MYENVoptions. You can also pass them inside of a file likeanka run --env-file environment.txt, where environment.txt is a text file in the formVARIABLE=VALUE, one variable per line.
Create
> anka create --help
usage: create [options] [name] [macOS version/installer file/installer url]
Creates a VM Template
arguments:
name VM name
macOS version/installer file/installer url
MacOS version (see --list), installer file location, or installer URL to use for creation (example: 'latest')
options:
-m,--ram-size <val> Specify the VM RAM size (supported suffixes: T|G|M|K)
-c,--cpu-count <val> Specify the number of vCPU cores for the VM (3 or more is recommended)
-d,--disk-size <val> Specify the VM disk size (supported suffixes: T|G|M|K)
--no-setup Do not perform automated macOS setup
-q,--quiet Do not show progress
-l,--list List available macOS versions to install
ARM USERS: The ipsw files will be downloaded intoimg_lib_dir. You can find the location of this directory withanka config img_lib_dir. These (and other temporary) files can be deleted withanka delete --cache.
A few tips when creating VMs:
We recommend naming your initial VM after the version of macOS.
Remember that VM templates are created under a specific user and will not be available to other users.
VM performance is important to our users. When setting CPUs for the VMs, 2vCPUs is usually not enough and can cause instability inside of the VM.
- ARM USERS: VCPUs are determined by taking the physical performance cores and multiplying by 2. This means you can set the CPU on creation for an M1 mini with 4 physical perf cores to
anka create --cpu-count 4, and run two VMs per host (8vCPUs available). - INTEL USERS: We recommend taking the total physical cores, doubling it, and then subtracting 2cpu. This leaves you with total virtual cores that can be used by VMs. If you plan to run 2 VMs at a time, divide the total vCPU in half and give the VM the result.
- ARM USERS: VCPUs are determined by taking the physical performance cores and multiplying by 2. This means you can set the CPU on creation for an M1 mini with 4 physical perf cores to
If you experience issues, run
anka --debug create. . .and provide it to Veertu’s support.You can re-enable SIP on intel VMs with
anka modify {vmNameOrUUID} set custom-variable sys.csr-active-config 0post-create.
RAM, DISK, and CPU are all set from the defaults under the Anka configuration:
❯ anka config | grep default | default_disk | 137438953472 | | default_nvcpu | 4 | | default_ram | 4294967296 |
INTEL USERS: Suspending VMs can sometimes produce a VM which is frozen on start. Usually this is because the hardware & cpu type you created the VM and suspended it on is different from the one you’re trying to start it on. Be sure to suspend your VMs on the same hardware that will be running VMs.
Anka Develop license (default): While you can create as many VMs as you wish, the free Anka Develop license only allows you to run one VM at a time and will only function on laptops (Macbook, Macbook Pro, and Macbook Air). It only supports a stopped VM state.
Anka Build license: When determining how many vcpus and ram your VM needs, you can divide the number of VMs you plan on running simultaneously within a host by the total virtual cores (vcpus) it has. So, if I have 12vCPUs on my 6core Mac Mini, and I want to allow 2 running VMs at once and not cripple the host machine, I will set the VM Template/Tag to have 6vcpus (12 / 2). However, with RAM, you’ll need to allow ~2GB of memory for the Anka Software and host ((totalRAM / 2)-1). Build licenses support suspended and stopped VM states.
Be aware of the user you’re executing Anka CLI commands as. If you create VMs as root, they won’t be available to other users on the system and vice versa.
You can bring you own .ipsw and .app files to use with anka create. This is an alternative to specifying the version from --list. It supports three different methods:
1. The specific macOS version from --list
ARM USERS: At the moment Apple only provides a public endpoint to list the latest macOS version.anka create --listwill therefore only show a single version. We are working to get them to publically list allipsw. In the meantime, Intel Anka does show all archived macOS versions for.app.
bash$ anka create -l
+---------------+---------+----------------------+
| version | build | post_date |
+---------------+---------+----------------------+
| 11.7.2 | 20G1020 | Dec 13 13:14:48 2022 |
+---------------+---------+----------------------+
| 12.6.2 | 21G320 | Dec 13 13:13:39 2022 |
+---------------+---------+----------------------+
| 13.1 (latest) | 22C65 | Dec 13 13:08:36 2022 |
+---------------+---------+----------------------+
| 13.0.1 | 22A400 | Nov 9 13:02:34 2022 |
. . .
bash$ anka create 11.7.2 11.7.2
75% [||||||||||||||||||||||||||||||||||||||||||||| ] 16:15 ETA
2. The location/path to the ipsw or .app on the host
bash$ anka create --cpu-count 5 --disk-size 100G 12.5.1 /Applications/macos-12.5.1.app
. . .
3. The URL to download the ipsw from (.app not supported)
bash$ anka create --cpu-count 5 --disk-size 100G 12.5.1 https://myCompanyIntranet/UniversalMac_13.1_22C65_Restore.ipsw
. . .
Start
> anka start --help
usage: start [options] vmid
Start or resume a VM
arguments:
vmid VM to start
options:
-f,--force Start VM with minimum checks
--login-passwd <val> Provide the user password (not needed if auto-login enabled - default)
-q,--quiet Minimize output
-v,--view Open VM in an Anka window
-u,--update-addons Start in (auto)update mode
Stop
> anka stop --help
usage: stop [options] [vmid...]
Shut down a VM(s)
arguments:
vmid VMs to stop
options:
-a,--all Shutdown all running VMs
-f,--force Forcefully stop the VM(s)
Clone
> anka clone --help
usage: clone [options] vmid [name...]
Clone a VM
arguments:
vmid VM to clone
name New VM name(s)
options:
-c,--copy Create an independent copy
-t,--tag <val> Clone particular VM tag (should be available locally)
Push
> anka push --help
usage: push [options] vmid [remote]
Push a VM to the registry
arguments:
vmid VM to push
remote Sets an alternate registry
options:
-t,--tag <val> Set the tag name to push (mandatory)
-v,--remote-vm <val> Registry template to push the tag onto
-d,--description <val> Set textual description of the tag
-f,--force Forcefully push, regardless of a tag already existing
-l,--local Commit the template without pushing it to the Registry
-s,--shallow Include all the changes of an older tags
-q,--quiet Do not show progress
Pull
> anka pull --help
usage: pull [options] vmid [remote]
Pull a VM template from the registry
arguments:
vmid VM to pull
remote Sets an alternate registry
options:
-t,--tag <val> Pull the particular tag (latest if not specfied)
-l,--local Checkout (make it current) local tag
--fetch-only Download tag without checkout
-s,--shrink Delete other local tags to optimize disk usage
--check-download-size Get the tag size only
-q,--quiet Do not show progress
Suspend
> anka suspend --help
usage: suspend [options] [vmid...]
Suspend a running VM(s)
arguments:
vmid VM to suspend
options:
-a,--all Suspend all running VMs
ARM USERS: Suspending will currently stop the VM. It will show as suspended, regardless.Mount
> anka mount --help
usage: mount [dir] [mntpoint]
Mount or check the mounted directories the VM
arguments:
dir Host directory to mount
mntpoint Corresponding mountpoint inside VM
Deprecated, please mount a network volume inside of the VM instead.
- Ensure File Sharing is on for the Host (System Preferences > Sharing).
- Click on (i) next to the File Sharing toggle button. Set up your Shared Folders to be mounted in the VM. In this example, I’ll mount my host’s home directory which is named
veertu.- I’ll then go under Options… and ensure the On checkbox is enabled to the left of the user I’m trying to log into the host with.
- Now use
anka runto mount the host share with SMB:anka run {VM} bash -c "mkdir -p ~/HOST; mount -t smbfs '//veertu[:password]@192.168.64.1/veertu' ~/HOST"We provide 192.168.64.1 inside of the VM which routes to the host.I can then access the host user’s home directory (
/Users/veertu) inside of the VM at~/HOST.❯ anka run test bash -c "df -h" . . . //[email protected]/veertu 932Gi 590Gi 342Gi 64% 154592960 89606492 63% /Users/anka/HOST
Unmount
> anka unmount --help
usage: unmount [options] [dir...]
Unmount the mounted directory
arguments:
dir Mountpoint, ID or host directory to unount
options:
-a,--all Unmount all mounted directories
Usb
> anka usb --help
usage: usb <command>
Manage USB devices
commands:
list List available usb devices
claim Make a device(s) available for attaching to a VM
release Release a device(s) back to host
usb list
> anka usb list --help
usage: list [device...]
List available usb devices
arguments:
device device to list
usb claim
> anka usb claim --help
usage: claim [options] device...
Make a device(s) available for attaching to a VM
arguments:
device device to claim
options:
-n,--claim-name Set the claim name / alternative name (can be reused and assigned to multiple devices for grouping
usb release
> anka usb release --help
usage: release [options] [device...]
Release a device(s) back to host
arguments:
device device to release
options:
-a,--all release all devices
Attach
> anka attach --help
usage: attach vmid device...
Attach USB device(s) to a running VM
arguments:
vmid VM to attach to
device device(s) to attach
Detach
> anka detach --help
usage: detach [options] vmid [device...]
Detach USB device(s) from a VM
arguments:
vmid VM to detach from
device device(s) to attach
options:
-a,--all detach all devices from the VM
Reboot
> anka reboot --help
usage: reboot [options] [vmid...]
Reboot a running VM(s)
arguments:
vmid VMs to reboot
options:
-a,--all Reboot all running VMs
Delete
> anka delete --help
usage: delete [options] [vmid...]
Delete a VM(s) and tags
arguments:
vmid VM to delete
options:
-a,--all Delete all VMs in library
-t,--tag <val> Specify local tag to delete
--yes Do not expect user confirmation of the operation
--cache Delete temporary cache and orphan images
Registry
> anka registry --help
usage: registry [options] <command>
Configure and control template registries
options:
-r,--remote <val> Sets an alternate registry
--insecure Skip TLS verification
--cert <val> Path to a client certificate (if user authentication is configured)
--key <val> Path to private key if the client certificate doesn't contain one
--cacert <val> Use custom CA certificates location (default is /etc/ssl/certs)
--api-key-id <val> UAK/TAP identity
--api-key <val> UAK/TAP key in PEM format (path or string)
commands:
list-repos List registries configured
add Add a registry
set Set default registry
remove Remove a registry from the configuration
list List templates in registry (see anka-push/pull commands)
show Show a template's properties
revert Delete a template or tag
registry list-repos
> anka registry list-repos --help
usage: list-repos [options] [name]
List registries configured
arguments:
name Show URL of the registry specified
options:
-d,--default Show the default registry name
registry add
> anka registry add --help
usage: add [options] name url
Add a registry
arguments:
name Registry name
url Registry URL
options:
-f,--force Do not perform a connectivity checks for the url
registry set
> anka registry set --help
usage: set [options] name [url]
Set default registry
arguments:
name Set default registry
url Registry URL if specified will be assigned to name
options:
-f,--force Do not perform a connectivity checks for the url
--cert <val> Path to a client certificate (if user authentication is configured)
--key <val> Path to a private key if the client certificate doesn't contain one
--cacert <val> Use custom CA certificates location (default is /etc/ssl/certs)
--api-key-id <val> TAP identity
--api-key <val> TAP key in PEM form
registry remove
> anka registry remove --help
usage: remove [options] [name...]
Remove a registry from the configuration
arguments:
name Registry name
options:
-a,--all Forget all registries
registry list
> anka registry list --help
registry show
> anka registry show --help
usage: show [options] vmid <command>
Show a template's properties
arguments:
vmid Template identifier or name
options:
-t,--tag <val> Specify template tag, latest by default
commands:
name Template name
uuid Template UUID
description Template description
tag Show template tags
cpu vCPU parameters
ram RAM size and parameters
display Display information
disk Disk information
network Network information
port Port forwarding rules
label Assigned template labels
Anka 2.x VMs never had the metadata for this to work. They will need to be re-pushed to the registry with Anka 3.x.
registry show {name/uuid} name
> anka registry show 14.3.1-arm64 name --help
registry show {name/uuid} uuid
> anka registry show 14.3.1-arm64 uuid --help
registry show {name/uuid} description
> anka registry show 14.3.1-arm64 description --help
registry show {name/uuid} tag
> anka registry show 14.3.1-arm64 tag --help
usage: tag [options]
Show template tags
options:
--latest Show the latest tag name
registry show {name/uuid} cpu
> anka registry show 14.3.1-arm64 cpu --help
registry show {name/uuid} ram
> anka registry show 14.3.1-arm64 ram --help
registry show {name/uuid} display
> anka registry show 14.3.1-arm64 display --help
registry show {name/uuid} disk
> anka registry show 14.3.1-arm64 disk --help
registry show {name/uuid} network
> anka registry show 14.3.1-arm64 network --help
registry show {name/uuid} port
> anka registry show 14.3.1-arm64 port --help
registry show {name/uuid} label
> anka registry show 14.3.1-arm64 label --help
usage: label [label]
Assigned template labels
arguments:
label Show particular label value
registry revert
> anka registry revert --help
usage: revert [options] vmid
Delete a template or tag
arguments:
vmid Template identifier or name
options:
-t,--tag <val> Delete particular template tag or latest by default
-a,--all Delete entire template from registry
--yes Do not expect user confirmation of the operation
Cp
> anka cp --help
usage: cp [options]
Copy files in/out of the Anka VM and host:
cp [options] <vmid>:path/inside </path/on/host>
cp [options] </path/on/host> <vmid>:[path/inside]
options:
-R copy the src and its entire subtree to the dst
-L all symbolic links are followed
-H symbolic links in the command are followed
-P do not follow a symbolic links (default)
-f remove and create the dst file on open failure
-n do not overwrite an existing file.
-p preserve the source file attributes
-a same as -pPR options
-v cause cp to be verbose, showing files as they are copied
❯ time anka cp ~/VirtualBox\ VMs/cloud-client-side-ha-1/cloud-client-side-ha-1.vdi 10.15.6:/Users/anka/
anka --debug cp 10.15.6:/Users/anka/ 0.86s user 20.60s system 4% cpu 8:53.85 total
Compare the ~9 minutes it takes for anka cp to how much it takes to transfer the same file with scp:
❯ time scp -P 10000 -v ~/VirtualBox\ VMs/cloud-client-side-ha-1/cloud-client-side-ha-1.vdi [email protected]:/Users/anka/
scp -P 10000 -v [email protected]:/Users/anka/ 110.61s user 60.88s system 22% cpu 12:46.30 total
License
> anka license --help
usage: license <command>
Manage licenses
commands:
show Show license information
activate Activate license key
validate Validate the current license
remove Remove the current license
accept-eula Accept EULA
license show
> anka license show --help
usage: show [options]
Show license information
options:
-k,--key <val> Get key information
license activate
> anka license activate --help
usage: activate [options] key
Activate license key
arguments:
key Activation key
options:
-f,--force Silently override the current license
--cid <val> Submit the CustomerID
license validate
> anka license validate --help
license remove
> anka license remove --help
license accept-eula
> anka license accept-eula --help
Export
- Only available for Enterprise or Enterprise Plus licenses.
- Exporting a VM is performing a unique copy like
anka clone -cwould do if it has no tags. - If you export a tagged VM in a chain (a VM that was cloned from another, or a tag on top of another VM tag), it will only export the VM layers that relate to that tag. You have to export and import all tags in the order they were created. This adds a fair bit of complexity though as each VM Tag is its own separate layer. When exporting, you’ll need to ensure the target is active on the host. To make it active, you can
anka pull --tag 1 templateA(--localmay speed this up if it was already pulled). Once active, exporting it requires--tag <val>.
This feature does not work if chunk_size is in use for the VM templates/tags.> anka export --help
usage: export [options] vmid file
Export a VM as an archive
arguments:
vmid VM to export
file Path to archive file
options:
-t,--tag <val> Export local VM tag
-c,--copy Include base tags into the archive
Import
> anka import --help
usage: import [options] file
Import VM from an archive
arguments:
file Archive with an exported VM
options:
--fetch-only Import tag without checkout