Templates and tags

Templates, full tags, thin tags, OCI tags, base tags, and push modes

Terms

TermMeaning
TemplateA VM that has at least one tag. In a registry, the template holds the tags for that VM.
TagA saved state of a template, such as vanilla or v1. A tag is a full tag or a thin tag.
Base tagThe tag that a newer tag builds on. If you push xcode-27.1 after vanilla on the same VM, vanilla is the base tag of xcode-27.1.
Full tagA tag that includes its base tags and the macOS disk. A VM can start from a full tag alone. The Anka Registry stores only full tags. An OCI registry stores a full tag when you push with push_mode 1 and without --thin.
Thin tagA tag that holds only file layers (a standard OCI filesystem layer / file-diff tarball). It does not include the macOS disk, so you pull it onto a VM that already exists. You make one when you push with --thin, or with push_mode 2, or when you push an archive. Public OCI artifacts, such as Homebrew bottles and Hugging Face GGUF models, are also thin tags. Only an OCI registry stores thin tags. Marketing calls these Portable Thin Tags.
OCI tagA tag in an OCI registry. An OCI tag is a full tag or a thin tag. See OCI tags.
AnkafileA file that lists the macOS version and the thin tags to pull, in order. anka create builds one VM from it. See Creating VMs with an Ankafile.

Local tags, clones, and how clones share disk layers are in VM clones, tags, and templates.

Full tags and thin tags

Full tags and thin tags behave differently on a VM. The type of tag sets the behavior. The registry does not.

  • A full tag includes the macOS disk. The Anka Registry stores only full tags. An OCI registry stores a full tag when you push with push_mode 1 and without --thin. A pull of a full tag puts the VM in the exact state of that tag. This occurs even if you changed the VM and did not push a new tag. The pull removes the thin tags that you pulled before it.
  • A thin tag holds only file layers. It does not include the macOS disk. Only an OCI registry stores thin tags. A pull of a thin tag adds its files to the VM. It does not remove files from the VM, unless the tag has a whiteout. Thin tags stack on the VM in the order that you pull them.
  • A second pull of a thin tag shows already up-to-date. Anka does not apply the same layers again.
  • Pull the full tag first, then the thin tags. Pro tip: keep a full tag under your thin tags. When the thin tags put the VM in a bad state, pull that full tag again to get a clean VM.

Thin pushes and pulls

Use --thin when you push or pull a tool as a thin tag. --thin uses only the last layer of a tag. The base tags stay out. Leave push_mode at 1 (the default). --thin applies only to an OCI registry.

For an example, see Push OCI tags with --thin.

Push modes

Prefer --thin for tool tags. Use push_mode only when you need a different store of the file changes. push_mode applies only to an OCI registry.

push_mode 1

This is the default in Anka 3.10.x. The push includes the base tag. Without --thin, the result is a full tag. A push to the Anka Registry always works this way.

Remember, both an OCI registry and the Anka Registry try to optimize disk usage. They reuse the disk images that the registry already has.

Example: 27.0.1-arm64:vanilla is already on a host. You anka pull cmake onto that VM, then push the result as 27.0.1-arm64:cmake.

On an Anka Registry or an OCI registry, cmake is a new tag whose base is the vanilla tag. The push reuses the vanilla tag the registry already has, so that tag stays unchanged. The registry stores the cmake tag on top of it.

push_mode 2

The push stores the changes since the base tag. The result is a thin tag. The base tag stays out of the manifest, so you can apply the tool tag onto another VM. It works only with an OCI registry.

With push_mode 2, that same push stores the file changes. The macOS base disk stays out of the manifest.

Set the push mode

❯ anka config push_mode 2
ANKA_PUSH_MODE sets the mode for one command. Use it when a change to anka config is a problem. Example: ANKA_PUSH_MODE=2 anka push 27.0.1 -t xcode-27.1 oci://registry.example.com/v2/

Exclude files from a push

When you push or export a VM with --thin or push_mode 2, Anka does not include the paths in the ankaignore file. The default file is /Applications/Anka.app/Contents/Resources/ankaignore. It excludes caches, logs, temporary files, and Spotlight data.

To exclude more paths, copy the default file, add your paths, and set the ankaignore config key to your copy:

❯ cp /Applications/Anka.app/Contents/Resources/ankaignore ~/ankaignore
❯ echo 'Users/*/Downloads' >> ~/ankaignore
❯ anka config ankaignore ~/ankaignore

To use a different file for one command only, set ANKA_ANKAIGNORE:

❯ ANKA_ANKAIGNORE=~/xcode.ankaignore anka push --thin xcode-builder -t xcode-26.1 oci://registry.example.com/v2/xcode

Anka also uses a .ankaignore file in the current directory. Put one in each tool’s build folder, then run anka push from that folder:

❯ cd ~/tools/xcode
❯ cp /Applications/Anka.app/Contents/Resources/ankaignore .ankaignore
❯ echo 'Users/*/Downloads' >> .ankaignore
❯ anka push --thin xcode-builder -t xcode-26.1 oci://registry.example.com/v2/xcode

Anka uses only one file. It uses the first file that it finds, in this order:

  1. .ankaignore in the current directory.
  2. The file in ANKA_ANKAIGNORE.
  3. The file in the ankaignore config key. If you do not change it, this is the default file.

Your file replaces the default file, so keep the default lines. The rules are like .dockerignore:

  • Each path is relative to the root of the VM disk, with no leading /. A path without a / matches that name in any folder.
  • * matches one folder level. ** matches any number of levels.
  • When you exclude a folder, Anka also excludes all of its contents.
  • A line that starts with ! keeps a path that a line above it excludes.
  • A line that starts with # is a comment.