Skip to main content
This guide will help you get BioAgents running with the minimum required configuration. For advanced features, see the complete Setup Guide.

​
Prerequisites

Before you begin, make sure you have:
  • Bun installed (required package manager)
  • Node.js v23.3.0 or later
  • A PostgreSQL database (we recommend Supabase for easy setup)
  • An OpenAI API key (or another LLM provider)

​
Installation

1

Clone the repository

git clone https://github.com/bio-xyz/BioAgents.git
cd BioAgents
2

Install dependencies

bun install
This will install all required packages including:
  • Elysia (web framework)
  • Anthropic, OpenAI, Google AI SDKs
  • Supabase client
  • Vector database dependencies
3

Configure environment variables

Create your environment file:
cp .env.example .env
Edit .env and configure the following required settings:
.env
# Authentication (use 'none' for development)
AUTH_MODE=none
BIOAGENTS_SECRET=change-me-to-a-secure-random-string

# LLM Configuration
OPENAI_API_KEY=sk-...
REPLY_LLM_PROVIDER=openai
REPLY_LLM_MODEL=gpt-4o
HYP_LLM_PROVIDER=openai
HYP_LLM_MODEL=gpt-4o
PLANNING_LLM_PROVIDER=openai
PLANNING_LLM_MODEL=gpt-4o
STRUCTURED_LLM_PROVIDER=openai
STRUCTURED_LLM_MODEL=gpt-4o

# Database
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-role-key

# Vector Embeddings
EMBEDDING_PROVIDER=openai
TEXT_EMBEDDING_MODEL=text-embedding-3-large

# Server
PORT=3000
NODE_ENV=development
Get your Supabase credentials from the Supabase Dashboard:
  • SUPABASE_URL: Settings > API > Project URL
  • SUPABASE_ANON_KEY: Settings > API > anon/public key
  • SUPABASE_SERVICE_KEY: Settings > API > service_role key (keep this secret!)
4

Set up the database

Run database migrations to create all required tables:
bun run migrate
This will apply migrations for:
  • Core tables (users, conversations, messages, states)
  • Vector database setup (pgvector extension)
  • Indexes, functions, and triggers
Make sure your SUPABASE_URL and SUPABASE_SERVICE_KEY are correctly set before running migrations.
5

Build the frontend

Build the Preact-based UI:
bun run build:client
The built files will be placed in client/dist/ and served by the backend.
6

Start the development server

bun run dev
The application will be available at http://localhost:3000
The dev server includes hot reload - changes to backend files will automatically restart the server.

​
Verify Your Setup

Once the server is running, you should see: 
[INFO] Server started on port 3000
[INFO] Vector database initialized
[INFO] Processing documents from docs/ directory
Open your browser to http://localhost:3000 and you should see the BioAgents chat interface.

​
Basic Usage

​
Chat Mode

Try asking a research question: 
What is rapamycin and what are its effects on longevity?
The agent will:
  1. Search available literature (if configured)
  2. Synthesize findings with citations
  3. Provide a comprehensive answer

​
Adding Custom Knowledge

To search your own documents:
1

Add documents to the docs folder

Place your documents in the docs/ directory:
docs/
├── research-paper-1.pdf
├── notes.md
└── dataset-description.txt
Supported formats: PDF, Markdown (.md), DOCX, TXT
2

Restart the server

The server will automatically process new documents on startup:
bun run dev
You’ll see:
[INFO] Processing document: research-paper-1.pdf
[INFO] Generated 15 chunks for research-paper-1.pdf
[INFO] Stored vectors in database
3

Query your knowledge base

The literature agent will now include your custom documents in search results.

​
Common Commands

# Start dev server with hot reload
bun run dev

# Watch UI changes
bun run client/build.ts --watch

​
Next Steps

You now have a basic BioAgents instance running! Here’s what to explore next:

Complete Setup

Configure advanced features like analysis agents, job queues, and payment protocols

Literature Agents

Set up OpenScholar, Edison, or BioLiterature for enhanced literature search

Analysis Agents

Configure Edison or BIO analysis agents for dataset processing

Authentication

Enable JWT authentication or x402 payments for production deployments

​
Troubleshooting

Make sure your Supabase credentials are correct:
# Test connection
curl https://your-project.supabase.co/rest/v1/ \
  -H "apikey: your-anon-key"
You should receive a valid response. If not, double-check your SUPABASE_URL and SUPABASE_ANON_KEY.
If migrations fail:
  1. Verify SUPABASE_SERVICE_KEY is set correctly
  2. Check that your database user has permission to create tables
  3. Try running migrations manually via Supabase SQL Editor
If you get API key errors:
  1. Verify your OPENAI_API_KEY is valid
  2. Check you have sufficient credits/quota
  3. Try using a different model (e.g., gpt-3.5-turbo for testing)
If custom documents aren’t being searched:
  1. Check that documents are in the docs/ folder
  2. Look for processing logs on startup
  3. Verify EMBEDDING_PROVIDER and TEXT_EMBEDDING_MODEL are set
  4. Check that pgvector extension is installed in your database
For more detailed troubleshooting and advanced configuration, see the complete Setup Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us