Installing Vaibify

Vaibify runs on macOS and Linux with Python 3.9 or later. It uses Docker (or Colima on macOS) to build and manage containers.

Prerequisites

Requirement	Version	Notes
Python	3.9 – 3.14	Any CPython release in this range
Docker	20.10+	Or Colima on macOS
Docker Buildx	0.10+	BuildKit-based image builder
Git	2.0+	For cloning repositories into images

Python and Git you likely have. For the other two see Installing Docker below — and note that neither is needed to start: a host project runs on your own machine with no container at all, which is how the QuickStart begins.

Users

Install the latest release from PyPI:

pip install vaibify

This installs the CLI, the Docker SDK, keyring integration, and the common data format libraries. A few specialist format readers live in an extra — see Data Format Libraries below.

Install into a Python built for your machine’s processor. On an Apple Silicon Mac an Intel-only Python (an older Anaconda, for example) runs through Rosetta, and everything installed into it stops working the day an operating-system upgrade removes that layer. Check before installing:

file "$(command -v python3)"
uname -m

The two must name the same architecture. vaibify doctor warns whenever the Python it runs under is being translated.

After installation, confirm the CLI is available:

vaibify --version

Multiple Vaibify projects can coexist on the same machine. Each project gets its own container, image, and workspace volume. Use vaibify init in each project directory to register it, then target any project from anywhere with --project/-p.

Developers

Clone the repository and install in editable mode:

git clone https://github.com/RoryBarnes/Vaibify.git
cd Vaibify
pip install -e ".[dev]"

The [dev] extra adds pytest-asyncio and httpx for running vaibify’s own internal test suite.

Data Format Libraries

The common formats work out of the box: h5py, openpyxl, Pillow, pyarrow, astropy and scipy are ordinary dependencies, so pip install vaibify brings them.

The specialist readers are not. pyvista, pysam, pyreadstat, pyreadr, safetensors, tfrecord and scapy live in the formats extra, because several of them need system libraries that a plain pip install cannot provide. Ask for them explicitly:

pip install 'vaibify[formats]'

See Supported Data Formats for the complete list.

Verify the installation:

vaibify --version
vaibify doctor

vaibify doctor runs the environment pre-flight (Docker context, daemon reachability, Colima health) and prints a status report; it works before any project exists.

The pytest test suite is not shipped in the pip package — it lives in the git repository. To run it, clone the repository and install the development extras:

git clone https://github.com/RoryBarnes/vaibify
cd vaibify
pip install -e '.[dev]'
pytest tests/            # add -m docker for the Docker-dependent tests

Shell Helpers

Shell completions and helper commands are configured automatically the first time any vaibify command is run after an install or an upgrade. No manual step is required, and nothing needs to be installed beyond the shell you already use: bash, zsh and fish are supported on macOS and Linux. The setup only ever appends to your shell’s configuration file (~/.zshrc, ~/.bash_profile on macOS or ~/.bashrc on Linux, ~/.config/fish/config.fish); it never edits or removes a line. The following aliases are added to your shell configuration:

Alias	Shorthand	Equivalent
vaibify_connect	vaib_connect	vaibify connect
vaibify_push	vaib_push	vaibify push
vaibify_pull	vaib_pull	vaibify pull

These commands work from any directory on the host. When multiple projects are registered, specify the target with --project/-p:

vaibify_connect -p my-project
vaibify_push -p my-project data.csv /workspace/data.csv
vaibify_pull -p my-project /workspace/results.csv ./results.csv

When only one project is registered, the --project flag can be omitted. See CLI Reference for details.

Tab completion

Press TAB after vaibify push or vaibify pull (or the aliases above) to complete a path:

• vaibify pull <TAB> offers the paths inside the project’s container; the destination is a path on your computer, which the shell completes as usual.

• vaibify push data.csv <TAB> offers container paths for the destination; the source is a file on your computer.

• Paths inside the project may be relative (Step01/output.csv) or absolute (/workspace/Step01/output.csv). A relative path is read from the project’s workspace root, and a completed path is accepted as typed.

• -p NAME is honored: the container that is listed is the one that vaibify push -p NAME would use. A host project has no container, so its container-side paths complete from the project’s own directory.

Nothing is offered while the container is stopped, and the completion never prints an error into your command line; run vaibify start and press TAB again. A name containing a control character is never offered, because it could move your terminal or split the list.

In bash, a path containing = or : is not completed (bash itself splits the word there), and a directory completes with a trailing space in bash 3.2, the version macOS ships as /bin/bash.

If TAB does nothing

Run vaibify doctor. Its shell-completions line reads the configuration file of the shell in $SHELL and, when it does not load vaibify’s completion script, prints the exact line to add in that shell’s syntax. Setup could not do it for you when the file was not writable, or when your login shell was a different one the first time.

To force the setup to run again, remove the marker file and invoke any command:

rm ~/.vaibify/.setup_done
vaibify --version

vaibify: command not found after an upgrade

The vaibify command is a two-line launcher whose first line names the Python that installed it. When that Python stops working, the launcher dies with it, and because your shell’s Python setup usually hides the error, the only symptom is command not found. The two common causes:

1. The Python was built for a different processor and ran through a translation layer the operating-system upgrade removed. On an Apple Silicon Mac the tell is Bad CPU type in executable when you run the interpreter directly.

2. The Python itself was replaced or removed – a package manager moved to a new minor version, or the developer tools were reinstalled and took their bundled Python with them.

Find the launcher and the interpreter it names:

find "$HOME" /opt /usr/local -maxdepth 4 -name vaibify -type f 2>/dev/null
head -1 <that path>

Run the interpreter named on that line. If it fails, the fix is not in vaibify: install a Python that runs natively on this machine (see Users), then reinstall vaibify and the other commands you rely on from it. Reinstalling the translation layer restores the old Python, but only until the next time the vendor withdraws it.

Installing for remote access

If you plan to drive this machine from another one with vaibify remote, vaibify must be on the non-interactive PATH of the user you will connect as. The test is exact:

ssh this-machine vaibify --version

It must print a version. A non-interactive SSH command does not read the shell files you normally edit – Ubuntu’s default .bashrc returns immediately for them – so a pip install --user, a virtualenv, or a conda environment activated by your profile will not be found, and vaibify remote will report that the remote produced no startup record.

Install somewhere already on the default PATH, symlink the entry point into /usr/local/bin, or extend the PATH above the non-interactive early-exit in that user’s shell configuration. Both machines also need the same vaibify version; a mismatch is refused rather than guessed at.

Browser Compatibility

The Vaibify dashboard runs locally and renders in your default browser. Vaibify targets evergreen desktop browsers; mobile browsers are out of scope. Any reasonably current Firefox, Chrome, Edge, or Safari works. The minimum versions below are set by the bundled terminal (xterm.js, which uses optional chaining and ResizeObserver), not only by the layout primitives — the terminal fails to load on older engines:

Browser	Minimum version	Released
Firefox	74	March 2020
Chrome / Edge	87	November 2020
Safari	14.1	April 2021

Below the Firefox floor the bundled terminal does not load at all (xterm.js fails to parse), so the in-container agent strip is unavailable; other panels may also render with collapsed spacing or misaligned modals.

Rendering a PDF figure uses the bundled pdf.js 3.11, which sets higher floors than the terminal does: Safari 15.4, Firefox 94 and Chrome / Edge 98. On an older engine the dashboard still loads, but PDF figures do not render. CI runs the browser tests in three engines (Chromium, Firefox and WebKit), so the current release of each is checked automatically; the versions in between are covered only by the floors above.

Installing Docker

Vaibify does not install a container runtime for you, and it does not need one until you build or run a container project: host mode works with no Docker at all. Install it when you want the isolation that Level 3 reproducibility is defined by.

Whichever platform you are on, confirm the result before going further. vaibify doctor runs the full pre-flight – Docker context, daemon reachability, Colima health – and prints a status report:

docker info          # must succeed WITHOUT sudo
docker buildx version
vaibify doctor

The docker info line is the one that catches most problems, and it must work as your own user: vaibify talks to the daemon as the user who runs it, never through sudo.

Docker on Linux

Distribution packages are often older than the Buildx floor above, so install Docker Engine from Docker’s own repository, following the current instructions for your distribution:

• Ubuntu

• Debian

• Fedora

• RHEL

Those pages are linked rather than transcribed because the repository setup changes; a copy here would go stale silently and leave you debugging a signing key. Install the docker-buildx-plugin package along with the engine – vaibify builds with BuildKit, and an engine without Buildx fails at the build rather than at the check.

Then grant your own user access to the daemon, which is what makes the docker info check above pass without sudo:

sudo usermod -aG docker "$USER"
newgrp docker          # or log out and back in

Be aware of what that grants: membership of the docker group is equivalent to root on the host, because a container can mount the host filesystem. On a shared or sensitive machine, prefer rootless mode, which vaibify works with unchanged.

One Linux-specific point about the in-container agent. A container reaches the hub through the Docker bridge gateway (172.17.0.1 by default), not through the host’s loopback interface, so on Linux the hub also listens on that gateway address. It asks the daemon for the address when it starts, and prints what it bound; if the daemon was not running at that moment the hub says so and listens on loopback only, in which case the dashboard works but vaibify-do inside the container cannot reach the hub. Start the daemon, then restart vaibify.

Finally, make sure the daemon starts with the machine:

sudo systemctl enable --now docker

Docker on macOS

On macOS, Colima is the recommended Docker runtime. Install with Homebrew or MacPorts:

Homebrew:

brew install colima docker docker-buildx
colima start --cpu 4 --memory 8

MacPorts:

sudo port install colima docker docker-buildx-plugin
colima start --cpu 4 --memory 8

If a Docker build takes more than a few minutes, macOS may sleep the Colima VM and corrupt the build. Prefix any long-running command with caffeinate -s to prevent this:

caffeinate -s vaibify build