# 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) [#quick-start-5-minutes]

1. Prerequisites [#1-prerequisites]

* **Python 3.11-3.14** (Python 3.12+ recommended)
* **Git** for cloning the repository
* **LLM Provider** (choose one):
  * [Claude API Key](https://console.anthropic.com/) (Recommended - best quality)
  * [AWS Bedrock Access](https://console.aws.amazon.com/) (For enterprise/AWS users)
  * [Google Gemini API Key](https://aistudio.google.com/apikey) (Free tier available)
  * [Ollama](https://ollama.com/) (Local, privacy-first)
* **NCBI API Key** (optional, for enhanced literature search)

2. Choose Installation Method [#2-choose-installation-method]

**Quick Decision:**

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

Global Installation (Recommended for Most Users) [#global-installation-recommended-for-most-users]

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

# Install Lobster globally
uv pip install lobster-ai
```

This makes `lobster` command available system-wide.

Local Installation (Project-Specific) [#local-installation-project-specific]

```bash
# 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 [#3-configure-api-keys]

Run the interactive configuration wizard:

```bash
# 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:**

```bash
# 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):**

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

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

```bash
# 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 [#4-test-installation]

**Global installation:**

```bash
# Command works from anywhere
lobster --help
lobster chat
```

**Local installation:**

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

# Then use Lobster
lobster --help
lobster chat
```

5. Your First Analysis [#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? [#what-can-lobster-do]

Single-Cell RNA-seq Analysis [#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 [#bulk-rna-seq-analysis]

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

Proteomics 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 [#multi-omics-integration]

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

Literature Mining [#literature-mining]

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

Essential Commands [#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 [#example-workflows]

Quick Dataset Analysis [#quick-dataset-analysis]

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

Literature-Guided Analysis [#literature-guided-analysis]

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

Multi-Dataset Integration [#multi-dataset-integration]

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

Custom Analysis [#custom-analysis]

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

Getting Help [#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

import { NextSteps } from '@/components/NextSteps';
import { BookOpen, Settings, FileText, MessageSquare } from 'lucide-react';

<NextSteps
  items={[
{
  href: "/docs/getting-started/installation",
  title: "Installation Guide",
  description: "Comprehensive installation options including Docker, development setup, and troubleshooting",
  icon: <BookOpen />
},
{
  href: "/docs/getting-started/configuration",
  title: "Configuration Guide",
  description: "Advanced configuration for API keys, model profiles, and cloud integration",
  icon: <Settings />
},
{
  href: "/docs",
  title: "Full Documentation",
  description: "Explore complete feature overview, tutorials, and API reference",
  icon: <FileText />
},
{
  href: "https://discord.gg/HDTRbWJ8omicsos",
  title: "Discord Community",
  description: "Join our community to get help, share workflows, and connect with other users",
  icon: <MessageSquare />
}
]}
/>

Troubleshooting Quick Fixes [#troubleshooting-quick-fixes]

**Installation fails?**

```bash
make clean-install  # Clean installation
```

**API errors?**

```bash
lobster config test  # Test API connectivity
```

**Memory issues?**

```bash
export LOBSTER_PROFILE=development  # Use lighter resource profile
```

**Need help?**

```bash
lobster chat  # Then type /help
```

Uninstalling [#uninstalling]

Remove Lobster [#remove-lobster]

**Global installation:**

```bash
uv tool uninstall lobster-ai
```

**Local installation:**

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

Remove User Data (Optional) [#remove-user-data-optional]

⚠️ Deletes all analysis history!

```bash
rm -rf ~/.lobster ~/.lobster_workspace
```

For more details, see the [Installation Guide](02-installation.md#uninstalling-lobster-ai).

***

**Ready to dive deeper?** Check out the [comprehensive installation guide](/docs/getting-started/installation) for advanced setup options, Docker deployment, and development installation.