Modifying your VM

Modify your VM using the Anka Virtualization CLI

Prerequisites

  1. You’ve installed the Anka Virtualization package.
  2. You’ve created your first VM.
The rest of this Getting Started guide focuses heavily on the (Command-Line Interface). These will be performed from within your macOS Terminal. For all available CLI commands, flags, and options, see the Command Reference.
> 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
  mount                    Add a host path to the VM's mounts

The goal is to give you a starting point for CPU and RAM on your VM Template, based on how many VMs you plan to run at once. Apple does not permit more than 2 VMs per machine (this is only a strict limitation on ARM machines currently).

Intel

To calculate the cores available for VMs, you’ll take the number of physical cores and then multiply it by 2. Once you have the total virtual cores, you can assign all of them (maybe - 1 or 2 CPUs to give the host breathing room) if you plan to run a single VM on the host. Otherwise, if you want to run two VMs at once, you’ll divide the total virtual cores by 2 and then assign this number to the VM Template. RAM follows a similar pattern, giving 2GB for the host: totalRAMGB - 2GB and (totalRAMGB / 2) - 2GB.

ARM

Use the host’s total CPU core count from Apple’s tech specs or sysctl hw.physicalcpu. Apple schedules guest vCPUs across the available cores — you do not need to account for performance vs efficiency cores separately. Note, though, that Apple mixes performance and efficiency cores, so the VMs are not guaranteed to be allocated to performance cores only.

CPU

  1. Find the host’s total core count (C):

    • On the host: sysctl hw.physicalcpu
    • Or use the CPU core count listed in Apple’s specs for your chip (e.g., an M4 Mac mini listed as 10-core → C = 10).

  2. Assign vCPUs to each VM template:

    • 1 VM: C, or subtract 1–2 if you want headroom for the host
    • 2 VMs: C / 2
    • Minimum: 4 vCPUs per VM. Values below 4 can cause instability inside the VM.
You can overcommit slightly for a 2 VM setup. But we cannot guarantee stability in these situations.

RAM

RAM follows the same pattern as Intel:

  • 1 VM: totalRAMGB - 2GB
  • 2 VMs: (totalRAMGB / 2) - 2GB
  • Mac Studio hosts: cap per-VM RAM at 60GB (Apple virtualization limit)

Worked examples

The following hosts show the formulas applied:

Example hostCores1 VM (CPUs)2 VMs (CPUs each)RAM (32GB host)
M4 Mac mini
10-core		108–105-630GB / 14GB
M4 Pro Mac mini
14-core		1412–147-830GB / 14GB
M4 Max Mac Studio
16-core		1614–168-930GB / 14GB (max 60GB)
M2 Ultra Mac Studio
24-core		2422–2412-1330GB / 14GB (max 60GB)

Common Examples

VM Resources

CPU

> anka modify 26.4.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 |
+-------+---+

RAM

> anka modify 26.4.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 |
+------+------+

DISK

> anka modify 26.4.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
IMPORTANT: Changing the disk size for a clone will break image chaining/“layer sharing” between the clone and its source. You’ll want to modify the source VM Template first, then clone it to a new 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.

Port forwarding from guest to host

> anka modify 26.4.1-arm64 port --help
usage: port [options] name [rule]

   Add port forwarding rule

arguments:
  name                     Rule name
  rule                     Port forwarding rule in form guest-port[:addr][:port]

options:
  -r,--reverse             Proxy from guest to an external address, e.g rule /var/run/syslog:/var/run/syslog
  -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-port is 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 ~ %

Changing your VM’s network configuration

Depending on your network topology, there are instances where you might need to use a bridge mode and assign your VM a unique IP address instead of the default shared IP of the host:

> anka modify 26.4.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"
  -n,--bond <val>          use bonding of [2-4] interfaces
  -v,--vlan <val>          assign VLAN ID, 0 to deassign
  -c,--controller <val>    set controller: anet, virtio-net
  --local                  allow vm-host connections (default)
  --no-local               prevent any vm-host connections
  -f,--filter <val>        filtering rules file, embed it into VM configuration with '-f- < rules.conf'), or use '-f off' to disable
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. This mode typically works with multiple interfaces on the host. Note: In order for your VM to see and use other interfaces on the host, you need to ensure the main interface for the host has at least one DNS server configured.
hostIt is very similar to the shared one, but the VM get IP addresses from range 192.168.128.2 - 192.168.128.254 and can’t access external networks outside of the host.
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 `--mac` for the network-card: `anka modify VmName network --type bridge --mac {MAC HERE}`

disconnectedThe VM will have a disconnected network cable.
natExperimental network mode for Apple Silicon/ARM, allowing at a minimum 2x 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 the hardware UUID and Serial with custom-variable (intel only)

At times you might need to modify the hardware serial or UUID to run proper builds/tests that require specific hardware to function properly:

> sudo anka modify 12.3.1 set custom-variable --help
Usage: anka modify set custom-variable [OPTIONS] KEY VALUE

  Set custom nvram & smb variables (Example: . . . set custom-variable hw.serial "<SERIAL>"

Options:
  --help  Display usage information

sudo anka modify {vmNameOrUUID} set custom-variable hw.uuid "GUID"
sudo anka modify {vmNameOrUUID} set custom-variable hw.serial 'MySerial'

What’s next?