Setup

Install Gardener, Then Connect a Machine

00 / BEFORE YOU START

One-Time Installation

Gardener is a desktop app for running biological data analysis pipelines, with optional execution on a remote machine. Part I gets the app installed. Part II connects it to a remote HPC, which handles the heavy compute.

We currently support three remote setups: a Slurm cluster, a single server over SSH, or a SPHERE testbed node. Part II adapts to whichever you pick.

Download the latest release Skip to remote setup

PART I

Desktop Setup

Installing on macOS or Windows, first launch, creating a project, and importing a dataset.

Install

Download from GitHub Releases and choose the latest version for your platform:

macOS Apple Silicon, .dmg
Windows .exe

Gardener GitHub Releases page listing the .dmg and .exe assets — Releases page

macOS

After downloading the dmg file, double click it and drag the app to Applications.

When it finishes, search for Lotus Biological Agent by pressing ⌘ + Space and open it.

Spotlight search opening Lotus Biological Agent — Open from Spotlight

If Gatekeeper still blocks the app, clear the quarantine flag instead:

xattr -d com.apple.quarantine "/Applications/Lotus Biological Agent.app"

Windows

Run the installer. At the SmartScreen prompt, choose next.

Select your preferred installation path and click Install.

Windows installer with installation path selection — Choose a path, then Install

First Launch

Open the app and wait for the backend to start.

Gardener landing page after the backend starts — Landing page

Create a Project and Import Data

Create a project.

New project dialog in Gardener — New project

Then import your dataset.

Import dataset view in Gardener — Import dataset

Add an LLM API Key

This step is optional. Skip it if you are not using any LLM features.

An LLM is not necessary for most dataset and samplesheet curation. A key is only needed for a few optional features, such as the LLM Annotation switch and resolving samplesheets whose columns are not sample / fastq_1. Everything else runs without one.

To add a key, open Settings at the bottom of the project sidebar, choose AI Model Config in the left nav, then select a provider, paste the key, and save.

Settings screen showing AI Model Config with provider and API key fields — Settings then AI Model Config

Accepted providers are OpenAI, Anthropic, Google, Google Gemma, Hugging Face, Mistral, Qwen, and DeepSeek.

Leave LLM Annotation off if no key is configured. The annotation step will fail rather than fall back.

PART II

Connect a Remote Machine

Required for the heavy compute that cannot run locally on macOS or Windows. Finish Part I first, then pick the connection that matches your machine. The steps below change to suit it.

Open the Connection Panel

Click HPC in the header, or HPC Connection in the sidebar footer.

HPC Connection entry points in the header and sidebar footer — HPC Connection entry point

Choose a Connection Type

Set Connection Topology to HPC via Slurm. This is the default, and the rest of this section covers that path.

Enter the Connection Details

Setting	Value
HPC Login Node / Remote Host	`user@login-host`
Workspace Root	`~/gardener_remote`, or use Browse

HPC Connection drawer with login node and workspace root fields — HPC Connection drawer

Under Advanced Backend Slurm Resources: CPU Cores 16, RAM 64 GB, Wall Time 24 h.

Advanced Backend Slurm Resources settings — Advanced Slurm resources

Set Up SSH

Set Up SSH Key → enter your cluster password in the terminal that opens.
Test SSH Connection → expect Connected to <host>.

Check Storage

Query Storage → confirm quota headroom if you want to check remote storage.

Connect

Click Connect to Remote Server. The first connection pulls two container images and is slow.

Before connecting to the remote server, be sure to connect to your organization’s VPN.

Disconnect

Close Remote HPC Process frees the Slurm allocation. Keep Remote HPC Process Running allows a fast reconnect.

These steps track the guides in the Gardener repository.