​
Getting Started

This guide walks you through installing BioCortex, configuring API keys, and running your first analysis via CLI or Web UI.

​
Prerequisites

  • Python 3.11+
  • (Optional) Conda for environment isolation
  • API keys for at least one LLM provider (OpenAI, Anthropic, Azure, or local e.g. Ollama)

​
Installation

cd /path/to/BioCortex_dev
bash install.sh            # Full install (conda + pip)
bash install.sh --minimal  # Core only (skip torch/multimodal)

​
Option B: Manual Install (Conda)

conda create -n biocortex_env python=3.11 -y
conda activate biocortex_env

pip install -r requirements.txt
pip install -e .

​
Option C: From environment.yml

cd /path/to/BioCortex_dev/biocortex_env
conda env create -f environment.yml
conda activate biocortex
pip install -e ..

​
Configure API Keys

Create a .env file in the project root (or in your home directory as ~/.biocortex/.env for per-user config): 
# Example: OpenAI
OPENAI_API_KEY=sk-...

# Or Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Or Azure OpenAI
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Or local (Ollama)
OPENAI_API_BASE=http://localhost:11434/v1
OPENAI_API_KEY=ollama
For reasoning, coder, and fast models you can set: 
REASONING_MODEL=gpt-4o
CODER_MODEL=gpt-4o
FAST_MODEL=gpt-4o-mini
See Configuration for all options.

​
Run Your First Analysis

​
CLI

conda activate biocortex_env
biocortex "Analyze single-cell RNA-seq data from pbmc.h5ad with clustering and cell type annotation"
Or interactive: 
biocortex
# Then type your task in natural language.

​
Web UI

  1. Start the backend and frontend:
# Terminal 1: FastAPI + WebSocket backend
python -m biocortex.web.app

# Terminal 2: Next.js frontend (if using separate frontend)
cd frontend && npm run dev
  1. Open the app (e.g. http://localhost:7860 or http://localhost:3000 depending on your setup).
  2. Log in, create or select a project, and type a biomedical task in the chat.
  3. The system will plan steps, execute them, and return a synthesized report.

​
Typical usage flow (Web UI)

  1. Log in — Open the app; sign in (or register if enabled).
  2. Project — Create a new task (project) or click an existing one in the sidebar. If you select an existing project, its conversation and results load into the chat view.
  3. Data (optional) — Upload files via the chat attachment or the Files page. Wait for the progress bar to finish.
  4. Send task — Type your request in natural language (e.g. “Run QC and clustering on my h5ad file”) and send. A “Preparing your analysis…” message appears immediately.
  5. Plan — The system returns a strategy (e.g. DAG) and a list of steps. Confirm the plan if the UI asks.
  6. Execution — Steps run in order (or in parallel by level). The plan panel shows progress (spinner → check or error). When the run finishes, all spinners stop and the report appears.
  7. Report — The Result Viewer shows the report with Figure 1, Figure 2, … and captions. You can download the report, export to PDF/Word, or generate a PowerPoint that uses the same figure numbering.
For a more detailed step-by-step and backend logic, see Web UI – Usage flow and Logic.

​
Verify Installation

# Core
python -c "from biocortex.agent import BioCortexAgent; print('OK')"

# Optional: browser tools
pip install playwright && playwright install chromium
python -c "from biocortex.tools.browser import BrowserTool; print('Browser OK')"

# Optional: cron / automation
python -c "from biocortex.automation import CronScheduler; print('Cron OK')"
See Quick Test Guide for more checks.

​
Next Steps

  • Architecture — Understand the seven functional layers.
  • Strategy Routing — How your task is classified (ReAct vs DAG vs MCTS).
  • Web UI — Chat, Projects, Resources, and Automation.