Skip to content

01 getting started

Jump to bottom
Tyo edited this page Jan 9, 2026 · 5 revisions

Getting Started with Lobster AI

Welcome to Lobster AI! This quick start guide will have you analyzing bioinformatics data in minutes.

Quick Start (5 minutes)

1. Prerequisites

  • Python 3.11+ (Python 3.12+ recommended)
  • Git for cloning the repository
  • LLM Provider (choose one):
  • NCBI API Key (optional, for enhanced literature search)

2. Choose Installation Method

Quick Decision:

  • Want lobster command everywhere? → Global Installation
  • Working on specific project? → Local Installation

Global Installation (Recommended for Most Users)

# Install uv if needed
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Lobster globally
uv tool install lobster-ai

This makes lobster command available system-wide.

Local Installation (Project-Specific)

# In your project directory
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install lobster-ai

This installs Lobster in your project's virtual environment only.

3. Configure API Keys

Run the interactive configuration wizard:

# For local installation, activate virtual environment first
source .venv/bin/activate  # Skip if using global installation

# Launch configuration wizard
lobster init

The wizard will guide you through:

  • ✅ Choosing your LLM provider (Anthropic, AWS Bedrock, Google Gemini, or Ollama)
  • ✅ Entering your API keys securely (input is masked)
  • ✅ Selecting model for your provider (e.g., Gemini 3 Pro vs Flash)
  • ✅ Optionally configuring NCBI API key for enhanced literature search
  • ✅ Creating two config files:
    • provider_config.json - Provider selection (safe to commit)
    • .env - API keys and secrets (never commit)

Configuration management:

# Test your configuration
lobster config test

# View current configuration (secrets masked)
lobster config show

# Reconfigure (creates backup)
lobster init --force

Manual configuration (advanced users only): If you prefer, create two files manually:

1. .lobster_workspace/provider_config.json (provider selection):

{
  "global_provider": "anthropic",
  "anthropic_model": "claude-sonnet-4-20250514",
  "profile": "production"
}

2. .env (API keys - never commit to git):

# Option 1: Anthropic API
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

# Option 2: AWS Bedrock
AWS_BEDROCK_ACCESS_KEY=your-aws-access-key
AWS_BEDROCK_SECRET_ACCESS_KEY=your-aws-secret-key

# Option 3: Google Gemini
GOOGLE_API_KEY=your-google-api-key
LOBSTER_LLM_PROVIDER=gemini

# Option 4: Ollama (local)
LOBSTER_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434

# Optional: NCBI API key
NCBI_API_KEY=your-ncbi-api-key-here

4. Test Installation

Global installation:

# Command works from anywhere
lobster --help
lobster chat

Local installation:

# Activate virtual environment first
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Then use Lobster
lobster --help
lobster chat

5. Your First Analysis

Try this example in the chat interface:

🦞 You: Download and analyze GSE109564 from GEO database

🦞 Lobster: I'll download and analyze this single-cell RNA-seq dataset for you...

[Downloads data and performs quality control, filtering, clustering, and marker gene analysis]

What Can Lobster Do?

Single-Cell RNA-seq Analysis

  • Quality control and filtering
  • Normalization and scaling
  • Clustering (Leiden algorithm)
  • Marker gene identification
  • Cell type annotation
  • Trajectory analysis

Bulk RNA-seq Analysis

  • Differential expression with pyDESeq2
  • Complex experimental design support
  • Batch effect correction
  • Pathway enrichment analysis

Proteomics Analysis

  • Mass spectrometry data processing
  • Missing value pattern analysis
  • Statistical testing with FDR control
  • Protein network analysis
  • Affinity proteomics (Olink panels)

Multi-Omics Integration

  • Cross-platform data integration
  • Joint clustering and analysis
  • Correlation network analysis
  • Integrated visualization

Literature Mining

  • Automatic parameter extraction from publications
  • PubMed literature search
  • GEO dataset discovery
  • Method validation against published results

Essential Commands

Once in the chat interface (lobster chat), try these commands:

Command Description
/help Show all available commands
/status Display system status and health
/files List files in your workspace
/data Show current datasets
/plots List generated visualizations
/read <file> Display file contents
/export Export complete analysis

Example Workflows

Quick Dataset Analysis

🦞 You: Load my_data.csv as single-cell RNA-seq data and perform standard analysis

Literature-Guided Analysis

🦞 You: Find optimal clustering parameters for my single-cell data based on recent publications

Multi-Dataset Integration

🦞 You: Load GSE12345 and GSE67890, then compare their cell populations

Custom Analysis

🦞 You: Perform differential expression between clusters 2 and 5 using a negative binomial model

Getting Help

  • Type /help in the chat for command reference
  • Check /status to verify system health
  • Use /files to see what data is available
  • Try /dashboard for system overview

Next Steps

Regardless of installation method (global or local), these guides work the same:

  1. Installation Guide - Detailed installation options
  2. Configuration Guide - Advanced configuration
  3. Main Documentation - Complete feature overview
  4. Discord Community - Get help from the community

Troubleshooting Quick Fixes

Installation fails?

make clean-install  # Clean installation

API errors?

lobster config test  # Test API connectivity

Memory issues?

export LOBSTER_PROFILE=development  # Use lighter resource profile

Need help?

lobster chat  # Then type /help

Uninstalling

Remove Lobster

Global installation:

uv tool uninstall lobster-ai

Local installation:

source .venv/bin/activate
pip uninstall lobster-ai
deactivate
rm -rf .venv  # Optional: remove virtual environment

Remove User Data (Optional)

⚠️ Deletes all analysis history!

rm -rf ~/.lobster ~/.lobster_workspace

For more details, see the Installation Guide.

Ready to dive deeper? Check out the comprehensive installation guide for advanced setup options, Docker deployment, and development installation.

Clone this wiki locally