Accessing your VM

Various ways to access your VM


  1. You’ve installed the Anka Virtualization package
  2. You’ve created and prepared your first VM Template
The Apple hypervisor and also Anka commands require an active and logged in user. You might have to VNC in to the host machine if you’re connected over SSH. This also means you need to disable any sort of sleep or even the passworded screensaver on macOS.

Anka run

Requires addons are installed inside of the VM. You can check if they are installed with the anka show {vmName} command.

Similar to docker exec, anka run allows execution of commands inside of a VM.

> anka run --help
usage: run [options] vmid

   Run a command inside of a VM

  vmid                     VM name or identifier (will be started if needed)

  -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          Run the command in background returning PID to wait with 'wait [PID...]' command
If the VM is in a stopped state, anka run will automatically start it.

You can use anka run on the host terminal to validate things are working properly:

❯ anka run 12.2.0-arm bash -c "hostname && ls -l && ping -c 5"
total 0
drwx------+  3 anka  staff    96 Oct 14 09:35 Desktop
drwx------+  3 anka  staff    96 Oct 14 09:35 Documents
drwx------+  3 anka  staff    96 Oct 14 09:35 Downloads
[email protected] 74 anka  staff  2368 Oct 19 11:31 Library
drwx------   4 anka  staff   128 Oct 19 11:14 Movies
drwx------+  3 anka  staff    96 Oct 14 09:35 Music
drwx------+  3 anka  staff    96 Oct 14 09:35 Pictures
drwxr-xr-x+  4 anka  staff   128 Oct 14 09:35 Public
PING ( 56 data bytes
64 bytes from icmp_seq=0 ttl=108 time=10.316 ms
64 bytes from icmp_seq=1 ttl=108 time=10.270 ms
64 bytes from icmp_seq=2 ttl=108 time=10.163 ms
64 bytes from icmp_seq=3 ttl=108 time=10.305 ms
64 bytes from icmp_seq=4 ttl=108 time=10.281 ms

--- ping statistics ---
5 packets transmitted, 5 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 10.163/10.267/10.316/0.055 ms
You may see the anka run command hang when using, for example, find. Opening the VM viewer will show a user approval dialog box saying “ankarund would like access to X”. Apple has locked down several locations from commands and enforces user interaction to approve. This is obviously a problem for automation, but, fortunately, there is a solution. You’ll need to either avoid using commands that recursively look at the file system locations, or, place the files you wish to find under a “resource” folder under /Users/anka. Executing find inside of the folder will not trigger the approval dialog box.

Shell Configuration Files / Environment

The anka run command doesn’t source .profile, .bash_profile, or .zshrc by default. It will however source .zprofile.

You have to source the files or use zsh/bash -lc/-ic before executing other commands. Here are some examples:

❯ anka run 12.2.0-arm bash -c "echo 'export TEST_ZSHRC=yes' >> ~/.zshrc"
❯ anka run 12.2.0-arm bash -c "echo 'export TEST_ZPROFILE=yes' >> ~/.zprofile"
❯ anka run 12.2.0-arm bash -c "echo 'export TEST_PROFILE=yes' >> ~/.profile"
❯ anka run 12.2.0-arm bash -c "echo 'export TEST_BASH_PROFILE=yes' >> ~/.bash_profile"
❯ anka run 12.2.0-arm env
❯ anka run test bash -c "env | grep TEST_"
❯ anka run test bash -ic "env | grep TEST_"
❯ anka run test bash -lc "env | grep TEST_"
❯ anka run test zsh -c "env | grep TEST_"
❯ anka run test zsh -ic "env | grep TEST_"
❯ anka run test zsh -lc "env | grep TEST_"
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.
Some advanced usage examples of anka run inside of a bash script can be found in our Getting Started repo’s VM Tag creation script.

Anka Viewer

Known Issues

  • Chrome, Edge, and any other GPU accelerated browser will not function due to limitations in Apple’s hypervisor. You would need to launch the browsers without GPU acceleration. For example, with Chrome: /Applications/Google\\ Chrome --disable-gpu.

With the CLI

The anka viewer requires an active UI session on the host (VNC is fine).
The anka view command currently will only function if you started the VM with anka start -uv.
> anka view --help
usage: view [options] vmid

   Open VM display

  vmid                     VM to view

  -d,--display <val>       Specify the display(s) to view
  -s,--screenshot          Take PNG screenshot
  --click                  Send HDI events
  --click-rec              Record HID events
  -o,--output <val>        Specify output file for the view operations

With the App

Instead of launching the viewer with the CLI, you can open the under /Applications and then double click on the VM in the list. This will launch the viewer window.


❯ anka modify 12.2.0-arm add port --guest-port 22 ssh

❯ anka show 12.2.0-arm network           
| mode       | shared     |
| controller | virtio-net |

| name | protocol | guest_port |
| ssh  | tcp      | 22         |

❯ anka start 12.2.0-arm

❯ anka show 12.2.0-arm network
| mode       | shared            |
| controller | virtio-net        |
| mac        | ce:73:f0:49:b1:3d |

| name | protocol | host_ip | guest_port | host_port |
| ssh  | tcp      | | 22         | 10000     |

❯ ssh [email protected] -p 10000
Last login: Fri Jan 14 17:46:28 2022
[email protected] ~ % 


Once you’ve enabled Apple’s Remote Login inside of the VM, simply add a forwarded port: anka modify 12.2.0-jenkins add port --guest-port 5900 vnc.

Answers to Frequently Asked Questions

  • anka run doesn’t support TTY mode, but you could easily use POSIX streams as with regular bash tool:

    ❯ anka run VNMANE whoami > /dev/null
    ❯ cat file-on-host.txt | anka run 12.2.0-arm md5
  • You can launch access macOS’ Recovery Mode through the menu. recovery-mode

What’s next?