Skip to main content
BioAgents is configured entirely through environment variables. This guide covers all available configuration options.

​
Core Configuration

​
Authentication & Security

​
BIOAGENTS_SECRET
string
required
Shared secret for API authentication (JWT signing/verification and API key).Generate with:
openssl rand -hex 32
Never commit this value to version control. Use a strong random value in production.
​
AUTH_MODE
string
default:"none"
Authentication mode for the API.Options:
  • none - No authentication required (development only)
  • jwt - Require JWT tokens signed with BIOAGENTS_SECRET (production)
x402/b402 payment authentication is controlled separately via X402_ENABLED/B402_ENABLED flags.
​
ALLOWED_ORIGINS
string
Comma-separated list of allowed origins for CORS requests.Required in production to prevent CSRF attacks. Leave empty for development (defaults to localhost:3000, localhost:5173).
ALLOWED_ORIGINS=https://bioagent-platform.bioagents.dev,https://app.bioagents.xyz
​
MAX_JWT_EXPIRATION
number
default:"3600"
Maximum JWT expiration time in seconds. Tokens with longer expiration will be rejected.Default: 3600 (1 hour)

​
Server Configuration

​
NODE_ENV
string
default:"development"
Node environment mode.Options:
  • development - Development mode with verbose logging
  • production - Production mode with optimized logging
​
PORT
number
default:"3000"
HTTP server port.

​
Database (Supabase)

​
SUPABASE_URL
string
required
Your Supabase project URL.Find in: Supabase Dashboard > Settings > API > Project URL
​
SUPABASE_ANON_KEY
string
required
Supabase anonymous key for client-side operations.Find in: Supabase Dashboard > Settings > API > anon public key
​
SUPABASE_SERVICE_KEY
string
Service role key for backend operations (bypasses Row Level Security).Required for production when RLS is enabled.Find in: Supabase Dashboard > Settings > API > service_role key
Keep this secret. It has full database access.
​
SUPABASE_FULL_URL
string
Full database connection URL for migrations.Used by migration containers. Format: postgresql://user:password@host:port/database

​
LLM Provider Configuration

See LLM Providers for detailed configuration.
​
OPENAI_API_KEY
string
OpenAI API key for GPT models.
​
ANTHROPIC_API_KEY
string
Anthropic API key for Claude models.
​
GOOGLE_API_KEY
string
Google API key for Gemini models.
​
OPENROUTER_API_KEY
string
OpenRouter API key for accessing multiple model providers.

​
LLM Model Selection

Each agent type can be configured with a specific provider and model:
​
REPLY_LLM_PROVIDER
string
default:"openai"
Provider for chat reply generation.Options: openai, anthropic, google, openrouter
​
REPLY_LLM_MODEL
string
default:"gpt-5"
Model for chat reply generation.
​
HYP_LLM_PROVIDER
string
default:"openai"
Provider for hypothesis generation.
​
HYP_LLM_MODEL
string
default:"gpt-5"
Model for hypothesis generation.
​
PLANNING_LLM_PROVIDER
string
default:"openai"
Provider for research planning.
​
PLANNING_LLM_MODEL
string
default:"gpt-5"
Model for research planning.
​
STRUCTURED_LLM_PROVIDER
string
default:"openai"
Provider for structured output generation.
​
STRUCTURED_LLM_MODEL
string
default:"gpt-5"
Model for structured output generation.
​
CONTINUE_RESEARCH_LLM_PROVIDER
string
default:"anthropic"
Provider for autonomous research continuation decisions.
​
CONTINUE_RESEARCH_LLM_MODEL
string
default:"claude-sonnet-4-5-20250929"
Model for autonomous research continuation decisions.

​
External Services

​
OPENSCHOLAR_API_URL
string
OpenScholar API endpoint for literature search.
​
PRIMARY_LITERATURE_AGENT
string
Primary literature search agent to use.
​
BIO_LIT_AGENT_API_URL
string
BioAgents Literature Agent API endpoint.
​
BIO_LIT_AGENT_API_KEY
string
API key for BioAgents Literature Agent.

​
Data Analysis

​
EDISON_API_URL
string
Edison API endpoint for literature and data analysis.Deploy from: bio-edison-api
​
EDISON_API_KEY
string
API key for Edison API.
​
PRIMARY_ANALYSIS_AGENT
string
Primary data analysis agent to use.Options:
  • edison or empty - Use Edison Data Analysis Agent (default)
  • bio - Use BioAgents Data Analysis Agent
​
DATA_ANALYSIS_API_URL
string
BioAgents Data Analysis Agent API endpoint.
​
DATA_ANALYSIS_API_KEY
string
API key for BioAgents Data Analysis Agent.
​
EMBEDDING_PROVIDER
string
default:"openai"
Provider for text embeddings.Options: openai, cohere
​
TEXT_EMBEDDING_MODEL
string
default:"text-embedding-3-large"
Model for text embeddings.
​
COHERE_API_KEY
string
Cohere API key (required if using Cohere embeddings or reranking).
​
CHUNK_SIZE
number
default:"2000"
Number of characters per document chunk.
​
CHUNK_OVERLAP
number
default:"200"
Overlap between consecutive chunks.
​
VECTOR_SEARCH_LIMIT
number
default:"20"
Number of vector search results to retrieve.
​
RERANK_FINAL_LIMIT
number
default:"5"
Number of results after reranking.
​
USE_RERANKING
boolean
default:"true"
Enable reranking of search results.
​
SIMILARITY_THRESHOLD
number
default:"0.75"
Minimum similarity score for vector search results.
​
RERANKER_SCORE_THRESHOLD
number
default:"0.3"
Minimum score for reranked results.
​
KNOWLEDGE_DOCS_PATH
string
default:"docs"
Path to knowledge documents for RAG.

​
Job Queue (BullMQ)

​
USE_JOB_QUEUE
boolean
default:"false"
Enable job queue with BullMQ and Redis.
  • false - In-process execution (simple, for development)
  • true - Queue jobs in Redis (for production, supports horizontal scaling)
​
REDIS_URL
string
default:"redis://localhost:6379"
Redis connection URL for BullMQ.Required when USE_JOB_QUEUE=true.
​
REDIS_HOST
string
default:"localhost"
Redis host (alternative to REDIS_URL).
​
REDIS_PORT
number
default:"6379"
Redis port (alternative to REDIS_URL).
​
REDIS_PASSWORD
string
Redis password (alternative to REDIS_URL).

​
Queue Concurrency

​
CHAT_QUEUE_CONCURRENCY
number
default:"5"
Number of concurrent chat jobs per worker.
​
DEEP_RESEARCH_QUEUE_CONCURRENCY
number
default:"3"
Number of concurrent deep research jobs per worker.
​
PAPER_GENERATION_CONCURRENCY
number
default:"1"
Number of concurrent paper generation jobs per worker.
​
MAX_CONCURRENT_PAPER_JOBS
number
default:"3"
Maximum concurrent paper jobs across all users.

​
Rate Limiting

​
CHAT_RATE_LIMIT_PER_MINUTE
number
default:"10"
Maximum chat requests per user per minute.
​
DEEP_RESEARCH_RATE_LIMIT_PER_5MIN
number
default:"3"
Maximum deep research requests per user per 5 minutes.

​
Bull Board Admin Dashboard

​
ADMIN_USERNAME
string
default:"admin"
Username for Bull Board admin dashboard.
​
ADMIN_PASSWORD
string
Password for Bull Board admin dashboard.Required in production when USE_JOB_QUEUE=true.

​
Task Timeouts

​
BIO_ANALYSIS_TASK_TIMEOUT_MINUTES
number
default:"60"
Timeout for BioAgents data analysis tasks (in minutes).
​
BIO_LITERATURE_TASK_TIMEOUT_MINUTES
number
default:"60"
Timeout for BioAgents literature search tasks (in minutes).
​
EDISON_TASK_TIMEOUT_MINUTES
number
default:"30"
Timeout for Edison tasks (in minutes).
​
FILE_STATUS_TTL_MINUTES
number
default:"60"
TTL for file status records (in minutes).

​
Autonomous Research Configuration

​
MAX_AUTO_ITERATIONS
number
default:"5"
Maximum autonomous iterations before asking user (when fullyAutonomous=false).When fullyAutonomous=true, the hard cap is 20 iterations regardless of this setting.

​
Storage Configuration

See Storage for detailed configuration.
​
STORAGE_PROVIDER
string
Storage provider for file uploads.Options: s3 (if empty or not set, storage is disabled)

​
Character Configuration

See Character for detailed configuration.
​
CHARACTER_FILE
string
default:"characters/bios.json"
Path to character configuration JSON file.Available characters:
  • characters/bios.json - Default BIOS scientific research assistant
  • characters/aubrai.json - Aubrai (Dr Aubrey de Grey persona for longevity research)
​
CHARACTER_JSON
string
Inline JSON string for character configuration (alternative to CHARACTER_FILE).Useful for simple deployments:
CHARACTER_JSON='{"name":"MyAgent","system":"You are MyAgent..."}'

​
Agent Identity

​
AGENT_NAME
string
Name used for paper authorship and prompts.If not set, papers will use “Anonymous” or just user email as author.
​
AGENT_EMAIL
string
Email used for paper authorship.

​
SEO Configuration

​
SEO_TITLE
string
Page title for SEO. Leave empty to use defaults.
​
SEO_DESCRIPTION
string
Page description for SEO. Leave empty to use defaults.
​
FAVICON_URL
string
URL to favicon. Leave empty to use defaults.
​
OG_IMAGE_URL
string
URL to Open Graph image. Leave empty to use defaults.

​
Development UI

​
UI_PASSWORD
string
Password to protect the development UI.Leave empty or remove this line to disable authentication.

​
Payment Protocols

See Authentication for detailed configuration of x402 and b402 payment protocols.

​
x402 (Base/USDC)

​
X402_ENABLED
boolean
default:"false"
Enable x402 payment protocol (USDC payments on Base network).

​
b402 (BNB Chain/USDT)

​
B402_ENABLED
boolean
default:"false"
Enable b402 payment protocol (USDT payments on BNB Chain).

​
Coinbase Developer Platform

​
CDP_API_KEY_ID
string
Coinbase Developer Platform API key ID.Required for x402 mainnet. Get from: CDP Portal
​
CDP_API_KEY_SECRET
string
Coinbase Developer Platform API key secret.
​
CDP_PROJECT_ID
string
Coinbase Developer Platform project ID.

​
Example Configuration

# Basic development setup
NODE_ENV=development
AUTH_MODE=none
PORT=3000

# Database
SUPABASE_URL=your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

# LLM
OPENAI_API_KEY=sk-...
REPLY_LLM_PROVIDER=openai
REPLY_LLM_MODEL=gpt-4

# In-process execution (no Redis needed)
USE_JOB_QUEUE=false

​
Next Steps

LLM Providers

Configure OpenAI, Anthropic, Google, and OpenRouter

Authentication

Set up JWT, x402, or b402 authentication

Storage

Configure S3 storage for file uploads

Character

Customize your agent’s persona

Build docs developers (and LLMs) love

Get started for freeTalk to us