Installation

Install

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

The script works on Linux and macOS, on x86_64 and arm64. 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. It asks for no root access and changes nothing outside those two directories. You can read it before you run it.

Check that it worked:

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.

Options

The script reads three environment variables:

Variable	Default	What it changes
`VOLANT_VERSION`	the newest release	The release to install, such as `v0.1.0-alpha.7`.
`VOLANT_HOME`	`~/.local/share/volant`	Where releases are unpacked.
`VOLANT_BIN_DIR`	`~/.local/bin`	Where the `volant` and `volant-playbook` links go.

curl -fsSL https://volant.sh/install.sh | VOLANT_VERSION=v0.1.0-alpha.7 sh

What you get

One binary. The release volant carries the agents it uploads to your hosts, so 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`.

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.

Linux or macOS.
The OpenSSH client on your PATH. Volant runs ssh itself, so your ~/.ssh/config applies.
For Python modules and fact gathering, a Python 3 with ansible-core installed. Volant uses ansible-core to build module payloads. It picks VOLANT_PYTHON first, then the active virtual environment, then python3 on your PATH.

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

Linux, x86_64 or arm64.
An SSH server and an account you can log into with a key or an ssh-agent.
A Python 3 interpreter for Python modules and fact gathering. The host does not need ansible-core: Volant sends every file a module imports.
sudo if you use become.

Nothing has to be installed by hand. The controller uploads the agent with the first task and caches it under ~/.ansible/tmp.

Update

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.

Other ways to install

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

This downloads the same release binary as the install script, agents included.

Every release on the releases page has one archive per platform, named volant-<target>.tar.xz, with a .sha256 file next to it. Unpack it and put volant on your PATH:

tar -xJf volant-x86_64-unknown-linux-musl.tar.xz
install -m 755 volant-x86_64-unknown-linux-musl/volant ~/.local/bin/volant

cargo install --git https://github.com/lorica-labs/volant volant

A build from source does not carry the agents, because they are cross-compiled for the hosts. Point VOLANT_AGENT_DIR at a directory that holds them, or build them from a checkout: cargo build leaves a local agent next to the controller, and just agent-musl builds the x86_64 Linux one. just smoke-embedded shows how a release build embeds them.

Uninstall

Remove the release directory, the links and the controller’s agent cache. On each host, the agent cache is one directory per account the run acted as:

rm -rf ~/.local/share/volant ~/.local/bin/volant ~/.local/bin/volant-playbook ~/.cache/volant
ssh web1 'rm -rf ~/.ansible/tmp/volant-agent-*'