RSS

Anka Virtualization 3.9.0

Ability to mount host directories inside of the VM

Starting in 3.9.0, we’ve added support for sharing host directories as inside of the VM.

High level

  • Supports multiple VMs mounting the same folder from host
  • Supports anka mount + anka unmount
  • Supports anka modify {vm} mount + anka modify delete mount so that you automatically mount the same location no matter what host is running the VM Template.
  • Survives VM reboots

Command line reference

> anka mount --help
usage: mount vmid [host_path[:guest_folder_name]]

   Mounts a host path to a running VM

arguments:
  vmid                     VM name or UUID
  host_path[:guest_folder_name]
                           Mount host_path and an optional guest_folder_name (which defaults to host_path folder name if not provided)

> anka unmount --help
usage: unmount [options] vmid [mount_ref...]

   Unmounts a host path from a running VM

arguments:
  vmid                     VM name or UUID
  mount_ref                Mount reference: fsid, guest_folder_name, or host_path to unmount

options:
  -a,--all                 Unmount all host paths from a running VM

> anka modify 26.4.1-arm64 mount --help
usage: mount host_path[:guest_folder_name]...

   Add a host path to the VM's mounts

arguments:
  host_path[:guest_folder_name]
                           Add host_path and an optional guest_folder_name (which defaults to host_path folder name) to template config

> anka modify 26.4.1-arm64 delete mount --help
usage: mount [options] [mount_ref...]

   Remove host folder mount(s) from template config

arguments:
  mount_ref                Mount reference: host_path, guest_folder_name, or host_path[:guest_folder_name]

options:
  -a,--all                 Delete all mount definitions

> anka show 26.4.1-arm64 mount --help

Examples

IMPORTANT: The folders you mount are all available under /Volumes/My Shared Files in the VM. This is not something we can change and is enforced by Apple.

❯ anka run test bash -c "ls -alht /Volumes/"
total 0
drwxr-xr-x   4 root  wheel   128B May  4 08:59 .
lrwxr-xr-x   1 root  wheel     1B May  4 08:59 Macintosh HD -> /
drwxr-xr-x  22 root  wheel   704B Apr  6 01:10 ..
drwxr-xr-x   1 anka  staff     0B Dec 31  1969 My Shared Files

❯ anka run test bash -c "ls -alht /Volumes/My\ Shared\ Files/"
total 0
drwxr-xr-x  4 root  wheel   128B May  4 08:59 ..
drwxr-xr-x  1 anka  staff     0B Dec 31  1969 .

❯ anka mount test ~/
/Volumes/My Shared Files/nathanpierce

❯ anka run test bash -c "ls -alht /Volumes/My\ Shared\ Files/"
total 16
drwxr-xr-x@ 245 anka  staff   7.7K May  4  2026 nathanpierce
drwxr-xr-x    4 root  wheel   128B May  4 08:59 ..
drwxr-xr-x    1 anka  staff     0B Dec 31  1969 .

❯ echo "hello" > ~/testfile1

❯ cat ~/testfile1
hello

❯ anka run test bash -c "cat /Volumes/My\ Shared\ Files/nathanpierce/testfile1"
hello

You can see what folders are mounted with:

❯ anka mount test
+------+---------------------+-------------------+---------------------------------------+
| fsid | host_path           | guest_folder_name | guest_path                            |
+------+---------------------+-------------------+---------------------------------------+
| 1    | /Users/nathanpierce | nathanpierce      | /Volumes/My Shared Files/nathanpierce |
+------+---------------------+-------------------+---------------------------------------+

❯ anka show test mount
+---------------------+---------------------------------------+
| host_path           | guest_path                            |
+---------------------+---------------------------------------+
| /Users/nathanpierce | /Volumes/My Shared Files/nathanpierce |
+---------------------+---------------------------------------+

You can disable the automounting of the volume that holds the folders in the VM globally in the host by changing anka config mount_prestart_automount_device to 0:

❯ anka config | grep automount
| mount_prestart_automount_device | 1

OCI Registry Support

In 3.9.0 we’ve added support for OCI registries. This allows you to store and pull VM templates from OCI registries like:

  1. ZOT (or any other strictly OCI compliant registry)
  2. Dockerhub
  3. ECR Public and Private Registries
  4. Jfrog Artifactory

Think of Anka VM Templates as Docker Images and Anka VM Tags as Docker Tags.

OCI registries are not currently compatible with the Anka Controller/Build Cloud. We will be adding support for this in a future release.
Registries must be OCI compliant and support the OCI Distribution API.

ZOT

ZOT is a simple OCI registry that can be used to store and pull Anka VM Templates.

In order to push, you need to specify the prefix -p to use for the VM templates.

❯ anka registry -p anka add zot http://127.0.0.1:15455

Once added, switch to the registry with anka registry set zot.

To push a VM template, you can use the anka registry push {vm} -t {tag} command.

Let’s say I pushed a VM template with the name 26.4.1-arm64 and the tag latest. This will create:

❯ ./zli-darwin-arm64 --url http://127.0.0.1:15455 repo list

REPOSITORY NAME
anka/26.4.1-arm64

Dockerhub

Dockerhub is a popular registry for Docker images. Fortunately, it’s ultimately OCI and we can use it to store and pull Anka VM Templates too.

❯ anka registry -p dockerhubUser -u dockerhubUser:dckr_pat_XXXXX add dockerhub https://registry-1.docker.io

The prefix is the either the org or user the repository is under. The -u is the username and password for the registry, colon separated. You can use a personal access token (PAT) for the password.

Once added, switch to the registry with anka registry set dockerhub.

To push a VM template, you can use the anka registry push {vm} -t {tag} command.

Let’s say I pushed a VM template with the name 26.4.1-arm64 and the tag latest. This will create a repository in Dockerhub with the name dockerhubUser/26.4.1-arm64 and a tag with the name latest.

ECR Public and Private Registries

For ECR, you can use registry add, but you will need to refresh the credentials every ~12 hours. The credentials used for AWS eventually expire and you need to refresh them.

AWS ECR requires use of the AWS CLI to authenticate. You must have a recent version of the AWS CLI installed and configured with the proper credentials.

Public Registries

An example of pulling a VM template from a public ECR registry of public.ecr.aws/veertu (a custom alias):

export ANKA_REGISTRY_AUTH_TOKEN=$(aws ecr-public get-authorization-token)
anka registry -o2 -p veertu -r https://public.ecr.aws pull VMNAME -t TAG
  • The prefix (-p) is the “alias” seen under Public Registry > Settings.
  • -o2 is the OCI Distribution API version.
  • -r is the registry URL.

This is the same for pushing.

Private Registries

For private ECR registries, you can use the same approach as public registries, but you will need the private URL instead of the public URL and use ANKA_REGISTRY_USER instead of ANKA_REGISTRY_AUTH_TOKEN.

export ANKA_REGISTRY_USER="AWS:$(aws ecr get-authorization-token)"
anka registry -o2 -p veertu -r https://4585690006.dkr.ecr.us-west-2.amazonaws.com pull VMNAME -t TAG
  • The prefix (-p) is the “alias” seen under Private Registry > Settings.
  • -o2 is the OCI Distribution API version.
  • -r is the registry URL.

Jfrog Artifactory

Jfrog’s artifactory uses the same approach as Dockerhub. See instructions above.