Command-line Reference

Anka CLI Reference
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
  suspend                  Suspend a running VM(s)
  mount                    Mount or check the mounted directories the VM
  unmount                  Unmount the mounted directory
  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
  license                  Manage licenses

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/tools/addons_create_update_disk                                                                                             |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| addons_hotupdate            | /Library/Application Support/Veertu/Anka/tools/addons_hotupdate.sh                                                                                                   |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| addons_identifier           | com.veertu.anka.addons.core.pkg                                                                                                                                      |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| addons_image                | /Library/Application Support/Veertu/Anka/guestaddons/anka-addons-mac.iso                                                                                             |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| addons_pkg                  | com.veertu.anka.guestaddons.pkg                                                                                                                                      |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| addons_postupdate           | /Library/Application Support/Veertu/Anka/tools/addons_postupdate.sh                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| adresses_per_byte           | 250                                                                                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| allow_nonunique_names       | False                                                                                                                                                                |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| anka_executable             | /Library/Application Support/Veertu/Anka/bin/ankahv                                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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           | /Library/Application Support/Veertu/Anka/bin/ankasc                                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bios_path                   | /Library/Application Support/Veertu/Anka/uefi/anka_code.fd                                                                                                           |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| block_nocache               | 1                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bridge_name                 |                                                                                                                                                                      |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ca_bundle                   | /Users/user1/.anka/ca-bundle.crt                                                                                                                              |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| catalog_url                 | https://swscan.apple.com/content/catalogs/others/index-13-12-10.16-10.15-10.14-10.13-10.12-10.11-10.10-10.9-mountainlion-lion-snowleopard-leopard.merged-1.sucatalog |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| chunk_size                  | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| create_suspend              | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| default_disk                | 137438953472                                                                                                                                                         |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| default_format              | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| default_nvcpu               | 4                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| default_passwd              | admin                                                                                                                                                                |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| default_ram                 | 4294967296                                                                                                                                                           |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| default_user                | anka                                                                                                                                                                 |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| delete_logs                 | 1                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| exit_delay                  | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| fvutil_executable           | /Library/Application Support/Veertu/Anka/bin/fvutil                                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| img_lib_dir                 | /Users/user1/Library/Application Support/Veertu/Anka/img_lib/                                                                                                 |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| img_path                    |                                                                                                                                                                      |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| implicit_mount              | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| install_tool                | /Library/Application Support/Veertu/Anka/tools/install_macos                                                                                                         |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| io_threads                  | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| log_dir                     | /Users/user1/Library/Logs/Anka/                                                                                                                               |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| log_file                    | anka.log                                                                                                                                                             |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| mac_random_bytes            | 2                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| max_vms_allowed             | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| mitigations                 | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| nice                        | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| nvram_path                  | /Library/Application Support/Veertu/Anka/uefi/anka_vars.fd                                                                                                           |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| operations_timeout          | 300                                                                                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| options_api_url             | https://8ewgf8mtn4.execute-api.us-west-2.amazonaws.com/prod/key/info                                                                                                 |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| permanent_mac_prefix        | 86,69,69                                                                                                                                                             |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| portfwd_base                | 10000                                                                                                                                                                |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| process_type                | Interactive                                                                                                                                                          |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| product_root                | /Library/Application Support/Veertu/Anka                                                                                                                             |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| propagate_license           | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| propagate_name              | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| pull_checkout               | 1                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| puller_threads              | 4                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| qncpu                       | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| quantum                     | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| qvcpu                       | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| registry_remotes_file_path  | /Users/user1/.anka/remote                                                                                                                                     |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| state_lib_dir               | /Users/user1/Library/Application Support/Veertu/Anka/state_lib/                                                                                               |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| table_fmt                   | grid                                                                                                                                                                 |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| tag_lib_dir                 |                                                                                                                                                                      |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| time_sync                   | 1                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| trim_disk                   | 1                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| uhost_executable            | /Library/Application Support/Veertu/Anka/bin/uhost                                                                                                                   |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| version_compat              | 0                                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| vlaunch_sock                | /var/run/vlaunchd                                                                                                                                                    |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| vm_lib_dir                  | /Users/user1/Library/Application Support/Veertu/Anka/vm_lib/                                                                                                  |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| vm_lock_dir                 | /Users/user1/.anka/locks                                                                                                                                      |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| vnc_password                | admin                                                                                                                                                                |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
❯ 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
  usb                      Show USB devices attached
❯ 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 13.1-openjdk-11.0.14.1-jenkins name --help

show {name/uuid} uuid

> anka show 13.1-openjdk-11.0.14.1-jenkins uuid --help

show {name/uuid} description

> anka show 13.1-openjdk-11.0.14.1-jenkins description --help

show {name/uuid} tag

> anka show 13.1-openjdk-11.0.14.1-jenkins tag --help
usage: tag [options]

   Local VM tags

options:
  --current                Show the currently checked out tag

show {name/uuid} cpu

> anka show 13.1-openjdk-11.0.14.1-jenkins cpu --help

show {name/uuid} ram

> anka show 13.1-openjdk-11.0.14.1-jenkins ram --help

show {name/uuid} display

> anka show 13.1-openjdk-11.0.14.1-jenkins display --help

show {name/uuid} disk

> anka show 13.1-openjdk-11.0.14.1-jenkins disk --help

show {name/uuid} network

> anka show 13.1-openjdk-11.0.14.1-jenkins network --help

show {name/uuid} port

> anka show 13.1-openjdk-11.0.14.1-jenkins port --help

show {name/uuid} label

> anka show 13.1-openjdk-11.0.14.1-jenkins label --help
usage: label [name]

   Show assigned VM labels

arguments:
  name                     Show particular label value

show {name/uuid} usb

> anka show 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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
  --local                  enable (default) inter-VM and VM-host communication
  --no-local               disable inter-VM and VM-host communication

modify {name/uuid} add disk

> anka modify 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins delete network --help

modify {name/uuid} delete disk

> anka modify 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins name --help
usage: name name

   Set new name for the VM

arguments:
  name                     New name

modify {name/uuid} cpu

> anka modify 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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
  --local                  enable (default) inter-VM and VM-host communication
  --no-local               disable inter-VM and VM-host communication
TypeDescription
sharedThe 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.
bridgeThe 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: ANKA_BRIDGE_NAME=en0
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 --direct-mac for the network-card: anka modify VmName network --mode bridge --direct-mac
disconnectedThe VM will have a disconnected network cable.
❯ 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 13.1-openjdk-11.0.14.1-jenkins 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 --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 test 22:0.0.0.0

❯ anka show 12.6 network
. . .
port_forwarding_rules:
+------+----------+------------+-----------+
| name | protocol | guest_port | host_port |
+------+----------+------------+-----------+
| test | tcp      | 22         | 10000     |
+------+----------+------------+-----------+

❯ anka start 12.6

❯ ssh [email protected] -p 10000
([email protected]) Password:
Last login: Fri Oct 14 06:37:54 2022
[email protected] ~ % 

modify {name/uuid} disk

> anka modify 13.1-openjdk-11.0.14.1-jenkins 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 0
It’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 13.1-openjdk-11.0.14.1-jenkins 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 13.1-openjdk-11.0.14.1-jenkins 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
  -v,--volume <val>        Mount a host directory into VM
  -n,--no-volume           Prevent implicit mounting of current folder (see --volume option)
  -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          Run the command in background returning PID to wait with 'wait [PID...]' command
Note: anka run will 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 12.6 bash -c "echo 'export TEST_ZSHRC=yes' >> ~/.zshrc"
anka run 12.6 bash -c "echo 'export TEST_ZPROFILE=yes' >> ~/.zprofile"
anka run 12.6 bash -c "echo 'export TEST_PROFILE=yes' >> ~/.profile"
anka run 12.6 bash -c "echo 'export TEST_BASH_PROFILE=yes' >> ~/.bash_profile"

anka run 12.6 env
XPC_SERVICE_NAME=com.veertu.anka.addons.ankarun
SSH_AUTH_SOCK=/private/tmp/com.apple.launchd.zX8qHCS8ON/Listeners
PATH=/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin
XPC_FLAGS=0x0
LOGNAME=anka
USER=anka
HOME=/Users/anka
SHELL=/bin/bash
TMPDIR=/var/folders/6c/8_zmsrb509j6xv075_9h22rm0000gn/T/
__CF_USER_TEXT_ENCODING=0x1F5:0x0:0x0
SHLVL=1

anka run 12.6 bash -c "env | grep TEST_"

anka run 12.6 bash -ic "env | grep TEST_"

anka run 12.6 bash -lc "env | grep TEST_"
TEST_BASH_PROFILE=yes

anka run 12.6 zsh -c "env | grep TEST_"

anka run 12.6 zsh -ic "env | grep TEST_"
TEST_ZSHRC=yes

anka run 12.6 zsh -lc "env | grep TEST_"
TEST_ZPROFILE=yes
To inherit the host’s environment, use the anka run -E (existing VM variables will not be overridden by host’s variables) or -e MYENV options. You can also pass them inside of a file like anka run --env-file environment.txt, where environment.txt is a text file in the form VARIABLE=VALUE, one variable per line.

Create

> anka create --help
usage: create [options] [name] [version]

   Creates a VM Template

arguments:
  name                     VM name
  version                  macOS version to install (use 'latest' to install the latest version)

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 into img_lib_dir. You can find the location of this directory with anka config img_lib_dir. These (and other temporary) files can be deleted with anka 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.
  • 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 0 post-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 --list will therefore only show a single version. We are working to get them to publically list all ipsw. 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 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.
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
  -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

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>       TAP identity
  --api-key <val>          TAP key in PEM form

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

registry show {name/uuid} name

> anka registry show 13.1-openjdk-11.0.14.1-jenkins name --help

registry show {name/uuid} uuid

> anka registry show 13.1-openjdk-11.0.14.1-jenkins uuid --help

registry show {name/uuid} description

> anka registry show 13.1-openjdk-11.0.14.1-jenkins description --help

registry show {name/uuid} tag

> anka registry show 13.1-openjdk-11.0.14.1-jenkins tag --help
usage: tag [options]

   Show template tags

options:
  --latest                 Show the latest tag name

registry show {name/uuid} cpu

> anka registry show 13.1-openjdk-11.0.14.1-jenkins cpu --help

registry show {name/uuid} ram

> anka registry show 13.1-openjdk-11.0.14.1-jenkins ram --help

registry show {name/uuid} display

> anka registry show 13.1-openjdk-11.0.14.1-jenkins display --help

registry show {name/uuid} disk

> anka registry show 13.1-openjdk-11.0.14.1-jenkins disk --help

registry show {name/uuid} network

> anka registry show 13.1-openjdk-11.0.14.1-jenkins network --help

registry show {name/uuid} port

> anka registry show 13.1-openjdk-11.0.14.1-jenkins port --help

registry show {name/uuid} label

> anka registry show 13.1-openjdk-11.0.14.1-jenkins 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

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