Use BioEngine now · What it enables · Deploy your own worker · Developer docs · Paper
Foundation models and curated repositories have transformed bioimage AI, yet most biologists cannot readily run, adapt, or extend them on available hardware. BioEngine fills this gap — deployable on a laptop, workstation, or cluster. Scientists screen models, fine-tune from the browser, enable real-time smart microscopy, and deploy analysis applications, all by describing their goal to an AI agent.
"The user does not need to know how BioEngine works internally. They describe what they want and receive the result. Infrastructure management stays with whoever runs the hardware. Scientific focus returns to the biologist."
The community BioEngine instance runs at BioImage.IO. Use it through the web dashboard or any AI agent — no installation, no IT ticket.
| BioEngine Dashboard | Browse all available BioEngine workers and open their management panels |
| Worker Dashboard | Deploy and manage apps on the public worker — cluster resources, running deployments, available apps |
| Deployment Wizard | Interactive setup guide for deploying your own BioEngine worker (Docker, SLURM, Kubernetes) |
Load the BioEngine skill in any AI agent (Claude, GPT-4, etc.) by providing this link:
https://bioimage.io/skills/bioengine/SKILL.md
The skill gives the agent a complete, plain-text description of every available service — inputs, outputs, and usage examples. The agent selects the appropriate workflow and dispatches it to the GPU hardware. No command-line access, software installation, or specialist knowledge required.
| Description | |
|---|---|
| Model screening | Agent queries the BioImage Model Zoo, filters by domain compatibility, runs inference across candidates, and ranks by mAP |
| Real-time inference | Live images stream from the microscope to BioEngine; per-frame statistics return to the controlling agent for closed-loop smart microscopy |
| Collaborative fine-tuning | Browser-based annotation against foundation model pre-segmentations; fine-tuning triggered with one click; models published back to the BioImage Model Zoo |
| Agent-built applications | Agent generates deployment manifest, GPU workflow, and web UI from a plain-language prompt; the resulting app is immediately callable by other agents |
BioEngine exposes all capabilities through a SKILL.md contract — a plain-text file designed for general-purpose AI agents to acquire domain knowledge and invoke GPU services directly. Any agent that reads the contract can screen models, trigger fine-tuning, or deploy a custom application, without any BioEngine-specific programming.
Facility managers and system administrators can deploy a private worker on any hardware. The interactive deployment wizard on BioImage.IO walks through the full setup for all supported modes.
| Mode | Use case |
|---|---|
| Single machine | Workstation, development, small-scale inference |
| SLURM / HPC | Auto-scaling on institutional HPC clusters (Apptainer) |
| Kubernetes | Production deployment with KubeRay |
# Docker — single machine quickstart
git clone https://github.com/aicell-lab/bioengine.git
cd bioengine
mkdir -p .bioengine data
UID=$(id -u) GID=$(id -g) docker compose upThe published ghcr.io/aicell-lab/bioengine-worker:0.9.0 image ships Ray 2.55.1. When connecting to a managed Ray cluster (KubeRay, Anyscale, etc.) Ray Client enforces an exact version match between driver and cluster — so you may need an image built against the version your cluster runs. Two ways:
Overlay on the published image (fast — pulls the image, rebuilds only the Ray install + env layers, ~1-2 min):
docker build \
--build-arg BIOENGINE_IMAGE=ghcr.io/aicell-lab/bioengine-worker:0.9.0 \
--build-arg RAY_VERSION=2.54.1 \
-f docker/worker-ray-overlay.Dockerfile \
-t bioengine-worker:0.9.0-ray2.54.1 .Full build from source (~5-10 min):
docker build \
--build-arg RAY_VERSION=2.54.1 \
-f docker/worker.Dockerfile \
-t bioengine-worker:0.9.0-ray2.54.1 .Both paths produce equivalent images. The active Ray version is exposed inside the image as $BIOENGINE_RAY_VERSION for diagnostics. The supported Ray range is >=2.33.0, <3.0.0 (set in pyproject.toml).
See Deployment Guide for full instructions for all modes.
from hypha_rpc import connect_to_server
server = await connect_to_server({"server_url": "https://hypha.aicell.io", "token": token})
worker = await server.get_service("bioimage-io/bioengine-worker")
status = await worker.get_status()
app_id = await worker.deploy_app(
artifact_id="bioimage-io/cellpose-finetuning",
application_id="cellpose-finetuning",
)pip install "bioengine[cli] @ git+https://github.com/aicell-lab/bioengine.git"
bioengine call bioimage-io/bioengine-worker get_status
bioengine apps list --worker bioimage-io/bioengine-worker| Method | Admin | Description |
|---|---|---|
get_status() |
Worker and cluster status | |
deploy_app(artifact_id, ...) |
✓ | Deploy an application |
stop_app(application_id) |
✓ | Stop a running application |
get_app_status(application_ids) |
Status of specific applications | |
list_apps() |
✓ | All deployed applications |
upload_app(files, workspace, hypha_token) |
Create/update application artifact | |
list_app_directories() |
✓ | List app working directories on disk |
clear_app_directory(application_id) |
✓ | Delete a stopped app's working directory |
run_code(code, ...) |
✓ | Run Python in a Ray task |
list_datasets() |
Available datasets |
BioEngine applications are self-contained deployable units: a manifest.yaml + Python deployment code + optional web frontend. They can compose multiple AI models, wrap models with custom pre/post-processing, and expose arbitrary web UIs. Once deployed, they register as Hypha services immediately discoverable and callable by other AI agents.
Reference apps:
apps/demo-app/— minimal single-deployment appapps/cellpose-finetuning/— browser-based collaborative fine-tuningapps/model-runner/— production BioImage Model Zoo inference
See Applications Guide.
┌────────────────────────────────────────┐
│ Hypha Server │
│ (RPC, service discovery, artifacts) │
└────────────┬───────────────────────────┘
│ WebSocket / RPC
┌────────────▼───────────────────────────┐
│ BioEngineWorker │
│ ┌─────────────────────────────────┐ │
│ │ Ray Cluster │ │
│ │ (SLURM / single / Kubernetes) │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ Applications Manager │ │
│ │ (Ray Serve lifecycle + │ │
│ │ artifact management) │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ Datasets Manager │ │
│ │ (Zarr HTTP streaming) │ │
│ └─────────────────────────────────┘ │
└────────────────────────────────────────┘
Stack: Ray + Ray Serve · Hypha · BioImage Model Zoo
git clone https://github.com/aicell-lab/bioengine.git
cd bioengine
pip install -e ".[worker,cli,dev]"
source .env # loads HYPHA_TOKEN
python -m bioengine.worker \
--mode single-machine \
--head-num-gpus 1 \
--workspace-dir ~/.bioengine \
--debug
pytest tests/end_to_end/ -v- Applications Guide — build and deploy BioEngine applications
- Datasets Guide — share and stream large scientific datasets
- Deployment Guide — single-machine, Kubernetes, and SLURM setup
Mechtel N, Dettner Källander H, Cheng S, Zhang H, AI4Life Consortium, Ouyang W. BioEngine: scalable execution and adaptation of bioimage AI through agent-readable interfaces. bioRxiv (2026). https://doi.org/10.64898/2026.04.19.719496
MIT — see LICENSE.
BioEngine is built on Ray, Hypha, and Zarr. Supported by the SciLifeLab & Wallenberg Data Driven Life Science Program (KAW 2020.0239), the Göran Gustafsson Prize (2317), AI4Life (EU Horizon Europe grant 101057970), and RI-SCALE (EU grant 101188168).