Installation

Lab is distributed as release archives, Docker images, and Go source. After installing it, run lab version to verify both Lab and the selected Ferret runtime.

Prebuilt binary

Download v2.0.0-alpha.35 for your platform from the Lab release page.

Release archives follow this naming pattern:

Platform	Archive
Linux x86_64	`lab_linux_x86_64.tar.gz`
Linux arm64	`lab_linux_arm64.tar.gz`
macOS x86_64	`lab_darwin_x86_64.tar.gz`
macOS arm64	`lab_darwin_arm64.tar.gz`
Windows x86_64	`lab_windows_x86_64.zip`
Windows arm64	`lab_windows_arm64.zip`

Extract the archive and place the lab binary in a directory on your PATH.

mkdir -p "$HOME/.ferret"
tar -xzf lab_linux_x86_64.tar.gz
mv lab "$HOME/.ferret/"
export PATH="$HOME/.ferret:$PATH"

terminal

$mkdir -p "$HOME/.ferret"$tar -xzf lab_linux_x86_64.tar.gz$mv lab "$HOME/.ferret/"$export PATH="$HOME/.ferret:$PATH"

On Windows, extract lab.exe from the zip file and place it in a directory included in PATH.

Docker

Lab release images are published to Docker Hub and GitHub Container Registry. Use the documented version tag so the container runs the same Lab version as these pages.

docker run --rm -v "$PWD/tests:/test" montferret/lab:2.0.0-alpha.35

terminal

$docker run --rm -v "$PWD/tests:/test" montferret/lab:2.0.0-alpha.35

The equivalent GitHub Container Registry image is ghcr.io/montferret/lab:2.0.0-alpha.35.

The container’s default command runs Lab against files mounted at /test. You can also pass an explicit Lab command:

docker run --rm -v "$PWD:/workspace" montferret/lab:2.0.0-alpha.35 \
  run --reporter=simple /workspace/tests

terminal

$docker run --rm -v "$PWD:/workspace" montferret/lab:2.0.0-alpha.35 \$  run --reporter=simple /workspace/tests

The container entrypoint treats run, serve, version, help, and leading flag arguments as Lab invocations. Other commands are executed directly in the container.

Build from source

Lab v2 is a Go module at github.com/MontFerret/lab/v2. Building v2.0.0-alpha.35 requires Go 1.26.0 or later.

git clone --branch v2.0.0-alpha.35 --depth 1 https://github.com/MontFerret/lab.git
cd lab
make build

terminal

$git clone --branch v2.0.0-alpha.35 --depth 1 https://github.com/MontFerret/lab.git$cd lab$make build

The build writes the binary to ./bin/lab.

For a narrower local compile, run:

go build -o ./bin/lab ./main.go

terminal

$go build -o ./bin/lab ./main.go

Verify installation

Run:

lab version

terminal

$lab version

The output includes the Lab binary version and the Ferret version reported by the selected runtime.

To verify a remote or binary runtime:

lab version --runtime=http://localhost:8080
lab version --runtime=bin:/usr/local/bin/ferret

terminal

$lab version --runtime=http://localhost:8080$lab version --runtime=bin:/usr/local/bin/ferret

Update

For a prebuilt installation, download the newer release archive and replace the existing lab binary. For Docker, change the image tag to the newer release and pull or run that image. Source builds should check out the newer release tag before rebuilding.

Uninstall

Remove the lab binary from the directory where you installed it. For the user-local path shown above:

rm "$HOME/.ferret/lab"

terminal

$rm "$HOME/.ferret/lab"

Do not remove the shared $HOME/.ferret directory if it contains the CLI configuration or other files. On Windows, remove lab.exe from its installation directory.

Next steps

Test authoring Writing Tests Write FQL unit tests and YAML query/assert suites. Test execution Running Tests Run local, HTTP, and Git-hosted test files with parameters and waits. Reference Configuration Reference Lab flags, defaults, environment variables, and runtime params.