Quick Start

This guide walks through the minimal steps to get a Vaibify project running on your machine. See Installing Vaibify for detailed installation instructions, or Setup Wizard for the interactive configuration walkthrough.

Option A: Build from an Existing Configuration

If a repository already contains a vaibify.yml (and optionally a workflow.json), you can build and run the container directly — no vaibify init required.

Clone the repository and navigate into it:

git clone git@github.com:user/my-project.git
cd my-project

Then build and start:

vaibify build
vaibify start

Any command run from inside a directory that contains a vaibify.yml will use that file automatically. No registration step is needed.

To target this project from other directories with --project/-p, register it:

vaibify register

Or register a project in a different directory:

vaibify register /path/to/my-project

If the configuration lists private repositories (URLs starting with git@github.com:), the build needs SSH key access. Ensure your SSH agent is running and the relevant keys are loaded:

ssh-add -l          # verify keys are loaded
vaibify build       # SSH agent is forwarded into the build

Skip ahead to Start and Connect once the build completes.

Option B: Initialize a New Project

Navigate to your project directory and run:

vaibify init

This creates a vaibify.yml configuration file and a container.conf repository list. Choose a template when prompted:

Template	Description
sandbox	No workflow. For exploration and interactive use.
workflow	Pipeline steps for reproducible data analysis.

Or specify a template directly:

vaibify init --template sandbox

See Templates for details on each template and how to create your own.

Build the Image

vaibify build

On first run this installs the base image, system packages, Python dependencies, and clones all repositories listed in container.conf. A rebuild is only required when vaibify.yml or container.conf change.

Start and Connect

vaibify start

This launches the container in the background. To open a shell inside it:

vaibify connect

Or use the shell alias (configured automatically on first run):

vaibify_connect

Transfer Files

Copy files into the container:

vaibify push localfile.txt /workspace/localfile.txt

Copy files out:

vaibify pull /workspace/output.csv ./output.csv

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

vaibify build -p my-project
vaibify start -p my-project
vaibify status -p my-project
vaibify connect -p my-project
vaibify push -p my-project data.csv /workspace/data.csv
vaibify stop -p my-project

Stop the Container

vaibify stop

The workspace volume persists between sessions. Use vaibify destroy to remove the container and optionally delete the volume.

Check Status

vaibify status

This reports whether the container is running, lists installed repositories, and shows resource usage.