Global Settings

Settings are searched for in one of the following files:

  • $HOME/.config/vagga/settings.yaml
  • $HOME/.vagga/settings.yaml
  • $HOME/.vagga.yaml

Supported settings:


Directory where to put images build by vagga. Usually they are stored in .vagga subdirectory of the project dir. It’s mostly useful when the storage-dir points to a directory on a separate partition. Path may start with ~/ which means path is inside the user’s home directory.


This options is designed specifically for Continuous Integration (CI) systems. When this option is set it identifies an environment variable that is used to specify the name of a subdirectory of the storage dir used for current project. It’s only useful if storage-dir is set.

For example, for gitlab you may want to set:

storage-subdir-from-env-var: CI_PROJECT_NAME

Or or alternatively:

storage-subdir-from-env-var: CI_PROJECT_NAMESPACE

Note: only dash, underscore, and alphanumerc chars are allowed in the name, all other characters will be replaced by dash (so technically clashes of names are possible). If this environment variable is empty, then vagga will fail.

Note 2: already set symlink in .vagga/.lnk overrides this setting. This also means that _init_storage_dir overiddes the setting. Which means you may not get immediate result when migrating from old system. You may remove the link though, if your CI system does not do that by default.

New in version 0.7.2.


Directory where to put cache files during the build. This is used to speed up the build process. By default cache is put into .vagga/.cache in project directory but this setting allows to have cache directory shared between multiple projects. Path may start with ~/ which means path is inside the user’s home directory.


The mapping of project paths to settings for this specific project.


    cache-dir: /home/myuser/.cache/myproject

Enable forwarding for proxy environment variables. Default true. Environment variables currently that this setting influence currently: http_proxy, https_proxy, ftp_proxy, all_proxy, no_proxy.


A list of variables and patterns that are propagated into the container by default. Example:

- "CI_*"

This is intended to use on CI system where parameters of build job is safe to propagate.

While technically you can specify “*” it’s very dangerous and error-prone option to enable.


A mapping of volume names to the directories inside the host file system.


The directories must exist even if unused in any vagga.yaml.

For example, here is how you might export home:

  home: /home/user

Then in vagga.yaml you use it as follows (prepend with /volumes):

  /root: !BindRW /volumes/home

See Volumes for more info about defining mount points.


  1. Usage of volume is usually a subject for filesystem permissions. I.e. your user becomes root inside the container, and many system users are not mapped (not present) in container at all. This means that mounting /var/lib/mysql or something like that is useless, unless you chown the directory
  2. Any vagga project may use the volume if it’s defined in global config. You may specify the volume in site-settings if you care about security (and you should).

A script to use for uploading a container image when you run vagga _push_image.

To push image using webdav:

push-image-script: "curl -T ${image_path} \${container_name}.${short_hash}.tar.xz"

To push image using scp utility (SFTP protocol):

push-image-script: "scp ${image_path} \${container_name}.${short_hash}.tar.xz"

The FTP(s) (for example, using lftp utility) or S3 (using s3cmd) are also valid choices.


This is that rare case where command is run by vagga in your host filesystem. This allows you to use your credentials in home directory, and ssh-agent’s socket. But also this means that utility to upload images must be installed in host system.


The name of the container as declared in vagga.yaml
The short hash of container setup. This is the same hash that is used to detect whether container configuration changed and is needed to be rebuilt. And the same hash used in directory name .vagga/.roots.

Set sysctls required by command. We do our best to only apply “safe” sysctls by vagga automatically. Still it may exhaust resources of your system, so use this option on your own risk.

We apply settings with sudo -k which means it will prompt for password each time setting is tuned (probably only after system reboot).

Settings currently exists:

Key in vagga.yaml Sysctl Name Hardcoded Limit
expect-inotify-limit fs.inotify.max_user_watches 524288

All project-local settings are also allowed here.

Project-Local Settings

Project-local settings may be in the project dir in:

  • .vagga.settings.yaml
  • .vagga/settings.yaml

All project-local settings are also allowed in global config.

While settings can potentially be checked-in to version control it’s advised not to do so.


If set to true (default) vagga will check if the container that is already built is up to date with config. If set to false vagga will use any container with same name already built. It’s only useful for scripts for performance reasons or if you don’t have internet and containers are not too outdated.


Set to your preferred ubuntu mirror. Default is currently a special url mirror:// which choses local mirror for you. But it sometimes fails. Therefore we reserve an option to change the default later.

The best value for this settings is probably http://<COUNTRY_CODE>


Enables -o Debug::NoLocking=yes. This is super-experimental, but allows to build multiple ubuntu images in parallel even when they use the same cache (i.e. in the same project, or when using cache-dir)


Set to your preferred alpine mirror. By default it’s the random one is picked from the list.


Alpine package manager is used not only for building Alpine distribution, but also internally for fetching tools that are outside of the container filesystem (for example to fetch git for Git or GitInstall command(s))


By default (build-lock-wait: false) vagga stops current command and prints a message when some other process have already started to build the image. When this flag is set to true vagga will wait instead. This is mostly useful for CI systems.


The mapping, that overrides environment variables set in container or command.

(default true) If the setting is true, when there is a symlink named yyy that points to a vagga, and vagga is run by calling the name of that symlink vagga finds a command with symlink-name which equals to this command and runs it directly, passing all the arguments to that command (i.e. vagga doesn’t try to parse command-line itself).

New in version 0.7.1.


(default false) When the setting is true then vagga will hash all the files inside the containers and will create a special signature file.

New in version 0.7.1.

This functionality is experimental. Use at your own risk.

(default false) This setting is paired with index-all-images. When both settings are true vagga will search identical files inside other containers and will replace the same files with hard links. This can significantly reduce a disk space occupied by the containers.

There are two precautions about this setting:

  1. Date modified, date created and most other metadata is ignored
  2. If you edit file directly in .vagga/<container-name> you may edit files in multiple containers at the same time (this is similar to transient-hard-link-copy in a some way)

New in version 0.7.2.

New in version 0.8.1: You can now use vagga _verify <container> to check that contents of the container match checksums in the index and are not mistakenly modified.

Similar to hard-link-identical-files but also makes hardlinks to containers of different projects. Similar precautions apply.

This option works only if storage-dir is specified.

This option optimizes disk space right after container is built. Use vagga _hardlink --global to optimize older containers.

New in version 0.8.1.


Disables auto-clean option in all containers. This is useful on CI systems where multiple parallel builds should work.


(default false) When building container, say mycontainer by default we use .tmp.mycontainer dir for building. This settings enables naming dir .tmp.mycontainer.1a2b3c4 where 1a2b3c4 is a container version being built.

Note: for some containers where we can’t determine version before building a container this setting does nothing.

It’s useful to turn this setting on on CI systems with configured storage_dir, when multiple versions of a single container could be being built simultaneously. It makes little sense to enable it on a workstation.