Setup

Install Gardener, Then Connect a Machine

00 / BEFORE YOU START

One-time Installation

Gardener (Lotus Biological Agent) is a desktop app for running biological data analysis pipelines, with optional execution on a remote machine. Part I gets the app installed and a first stage running on your own laptop — no API key, no cluster. Part II connects it to a remote machine, which is required for sandbox execution because that cannot run locally on macOS or Windows.

Three remote topologies are supported — a Slurm cluster, a single server over SSH, or a SPHERE testbed node. Pick one in Part II and the steps follow your choice.

Download the latest release Skip to remote setup

Prefer to watch first? This walkthrough covers the install, the first project, and an scRNA run end to end.

PART I

Desktop Setup

Installing on macOS or Windows, first launch, creating a project, importing a dataset, running a stage, and configuring the AI model.

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

Run a Stage

Select the dataset.
Pick a stage and fill in the form.
Choose Run This Stage, or Run Pipeline.

Stage configuration form with the Run This Stage button — Stage form and Run button

No LLM API key is required for this path.

Pipeline Walkthroughs

One demo per assay, each running the pipeline start to finish. Single-cell RNA is covered in the intro walkthrough at the top of this page.

Add an LLM API Key

Optional — skip it if you are not using LLM features.

Required only for:

agent chat
sandbox execution
the LLM Annotation switch
resolving samplesheets whose columns are not sample / fastq_1

Open Settings at the bottom of the project sidebar.
Choose AI Model Config in the left nav.
Select a provider, paste the key, and save.

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

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

Leave LLM Annotation off if no key is configured — the annotation stage will fail rather than fall back.

PART II

Connect a Remote Machine

Required for sandbox execution, which cannot run locally on macOS or Windows. Finish Part I first, then pick the topology 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 the Topology

Set Connection Topology to HPC via Slurm — this is the default. The rest of this section covers that path.

Fill in the Fields

Field	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.