Skip to content
Install

Installation

Install Volant with one command, check what the controller and the hosts need, and keep it up to date.

Terminal window
curl -fsSL https://volant.sh/install.sh | sh

The script works on Linux and macOS, on x86_64 and arm64. On Linux it takes the static build. It needs curl, tar and sha256sum or shasum, plus xz on Linux. It downloads the newest release for your machine, checks its SHA-256 checksum, unpacks it under ~/.local/share/volant, and links volant and volant-playbook into ~/.local/bin. The script asks for no root access and writes nothing outside those two directories. What Volant writes later, when it runs, is listed in What Volant leaves on your machines. You can read the script before you run it. Windows is not supported yet: a Windows controller is on the roadmap.

You do not need Ansible installed. On the first run that needs Python, Volant downloads its own copy of Python and ansible-core, about 155 MB, and keeps it in ~/.local/share/volant/runtime. It prints one line when it does. What Volant leaves on your machines lists everything it writes.

Check that it worked:

Terminal window
volant --version

If your shell cannot find volant, add ~/.local/bin to your PATH. The script prints the line to add when it is missing.

The script reads four environment variables and takes one option, --shims, which does what VOLANT_SHIMS=1 does:

Variable Default What it changes
VOLANT_VERSION the newest release The release to install, such as v0.1.0-alpha.10.
VOLANT_HOME ~/.local/share/volant Where releases are unpacked.
VOLANT_BIN_DIR ~/.local/bin Where the volant and volant-playbook links go.
VOLANT_SHIMS unset Set to 1 to also link the ansible-* names. See below.
Terminal window
curl -fsSL https://volant.sh/install.sh | VOLANT_VERSION=v0.1.0-alpha.10 sh

Add --shims and the script also links the nine ansible-core program names to volant, so existing command lines keep working: ansible, ansible-config, ansible-console, ansible-doc, ansible-galaxy, ansible-inventory, ansible-playbook, ansible-pull and ansible-vault.

Terminal window
curl -fsSL https://volant.sh/install.sh | sh -s -- --shims
curl -fsSL https://volant.sh/install.sh | VOLANT_SHIMS=1 sh

Ansible command names lists what each name runs and what differs. The script never installs them by default. It runs volant shims install, which leaves a file or link it did not make alone and says when a real Ansible on your PATH is hidden or still runs first. If a name could not be linked, the script prints some ansible-* names were not linked, see above and still exits 0, because Volant is installed.

The setup-volant action installs Volant in a workflow. It runs the install script above, so it checks the same SHA-256 checksum, and it adds the directory of the volant link to the PATH of the steps that follow. It works on Linux and macOS runners.

steps:
- uses: actions/checkout@v7
- uses: lorica-labs/volant/setup-volant@main
with:
version: v0.1.0-alpha.13
shims: true
- run: ansible-playbook -i inventory.yml site.yml

uses: takes a branch, a tag or a commit of the volant repository. The action is in every release after 0.1.0-alpha.13. Pin version as well, so a new release does not change what the workflow runs.

Input Default What it does
version the newest release The release to install, such as v0.1.0-alpha.13.
shims false Also link the ansible-* names, as --shims does.
runtime false Install the managed runtime in this step instead of on the first run that needs it.
collections empty Collections to install into the runtime, as with volant runtime install --collections: names with an optional :version, or a requirements file, separated by spaces or new lines.
python empty Sets VOLANT_PYTHON. Runs then use that interpreter and never install the runtime.

With runtime or collections, the action caches the runtime directory with actions/cache. The cache key is made of the runner’s system and architecture, the Volant version, the collections and the content of any requirements file among them, so a later run with the same inputs restores the runtime instead of downloading it.

The release has two executables. volant carries the agents it uploads to your hosts. An agent is a small program that runs your tasks on a host. There is nothing else to install and nothing to keep next to it:

File What it is
volant The controller, the command you run.
volant-playbook The same controller under a name that reads like ansible-playbook.
ansible, ansible-vault and the other seven names Optional links to volant, only with --shims. See Ansible command names.

On first use, the controller writes its agents to ~/.cache/volant/agents/<version>/, or under $XDG_CACHE_HOME when it is set: the agent for your own machine, used by ansible_connection=local, and the ones it uploads to x86_64 and arm64 Linux hosts. Later runs reuse them, and a copy that does not match the agent built into the controller is written again.

Every release has one archive per platform. Linux has a static build and a glibc build. macOS has one build, which links the system libraries.

Platform Archive Linkage Minimum Needs beside it
Linux x86_64, static volant-x86_64-unknown-linux-musl.tar.xz Static. No libc. Any Linux ssh client, Python for Python modules
Linux x86_64, glibc volant-x86_64-unknown-linux-gnu.tar.xz Dynamic, glibc only glibc 2.17 ssh client, Python for Python modules
Linux arm64, static volant-aarch64-unknown-linux-musl.tar.xz Static. No libc. Any Linux ssh client, Python for Python modules
Linux arm64, glibc volant-aarch64-unknown-linux-gnu.tar.xz Dynamic, glibc only glibc 2.17 ssh client, Python for Python modules
macOS, Apple silicon volant-aarch64-apple-darwin.tar.xz Dynamic, system libraries only macOS 11 ssh client, Python for Python modules
macOS, Intel volant-x86_64-apple-darwin.tar.xz Dynamic, system libraries only macOS 10.12 ssh client, Python for Python modules

Both Linux builds run the same code and carry the same agents. The static build runs on any distribution, including Alpine and a container with no libc. The glibc build needs glibc 2.17 or newer, which covers Debian 8, Ubuntu 14.04, RHEL and CentOS 7 and everything after them, and it takes the security updates of the system libc.

The install script always takes the static build on Linux. volant-installer.sh takes the glibc build on glibc 2.17 or newer and the static build on any other Linux. cargo binstall takes the glibc build on any glibc host and the static build on Alpine. On a glibc host older than 2.17, download the static archive by hand.

The static build needs nothing from the image, so it runs in a container built FROM scratch:

FROM scratch
COPY volant /volant
ENTRYPOINT ["/volant"]

A scratch image has no ssh, no Python, no shell and no /etc/passwd. With only the controller in it, a playbook can run on connection: local and use command with argv. SSH connections need an ssh client in the image, Python modules and fact gathering need Python, and shell and raw need a shell. The controller keeps the agent it extracts under ~/.cache/volant, or under $XDG_CACHE_HOME when it is set: give it a directory it can write.

  • Linux or macOS.
  • The OpenSSH client on your PATH. Volant runs ssh itself, so your ~/.ssh/config applies.
  • curl or wget, and tar, the first time a playbook needs Python.
  • To use the install script or unpack a release by hand, curl, tar, sha256sum or shasum, and xz on Linux.

For the modules that run in Python, Volant uses a Python 3 with ansible-core. When it finds none, it downloads its own (about 155 MB), checks every file against a pinned hash and keeps it under ~/.local/share/volant/runtime. A run that does this prints one line. If you already have such a Python, Volant can use it: Which interpreter a run uses gives the order. See The managed runtime.

Volant has a command for each ansible-core program, and the install script can link the ansible-* names to them. Ansible command names says which ones run in Volant and which run ansible-core’s own tool from the managed runtime.

A playbook made only of command, shell, raw and controller-side modules, with gather_facts: false, needs no Python at all.

Run the install command again. It installs the newest release next to the ones you have and points the links at it. Older releases stay under ~/.local/share/volant, so going back is a matter of setting VOLANT_VERSION.

Terminal window
# Only pre-releases exist so far, so name the version.
cargo binstall volant@0.1.0-alpha.10

This downloads a release binary with its agents included. On a glibc host it is the glibc build, on Alpine the static build.

Remove the release directory, the links and the controller’s caches. On each host, the agent cache is one directory per account the run acted as. Nothing else in your project changes, so going back to ansible-playbook needs nothing more:

Terminal window
volant runtime remove --all
volant shims remove
rm -rf ~/.local/share/volant ~/.local/bin/volant ~/.local/bin/volant-playbook ~/.cache/volant
ssh web1 'rm -rf ~/.ansible/tmp/volant-*'