Skip to main content
BioAgents can be deployed in multiple configurations depending on your scale and reliability requirements.

​
Architecture Patterns

​
Simple Deployment

Single container running both API server and job processing in-process. Best for:
  • Development environments
  • Low-traffic deployments
  • Quick demos and prototypes
docker run -p 3000:3000 \
  -e USE_JOB_QUEUE=false \
  -e OPENAI_API_KEY=your-key \
  bioagents:latest

​
Production Deployment

Separate API server and worker processes with Redis queue. Best for:
  • Production environments
  • High-traffic applications
  • Horizontal scaling requirements
  • Reliability and fault tolerance

​
Deployment Options

Docker Compose

Deploy using docker-compose for local or single-server production

Job Queue

Configure BullMQ with Redis for reliable background processing

Horizontal Scaling

Scale workers across multiple servers for high throughput

​
Service Components

​
API Server

Responsibilities:
  • Handle HTTP requests and WebSocket connections
  • Enqueue jobs to Redis
  • Broadcast real-time notifications to clients
  • Serve static frontend files
Scaling: Can scale horizontally with a load balancer. WebSocket connections require sticky sessions.

​
Worker Process

Responsibilities:
  • Process jobs from Redis queues
  • Execute AI agent workflows
  • Publish progress notifications via Redis Pub/Sub
  • Update database with results
Scaling: Can scale horizontally without any coordination. Workers automatically share the queue.

​
Redis

Responsibilities:
  • Message broker for BullMQ queues
  • Pub/Sub for real-time notifications
  • Job state persistence
Scaling: Can use Redis Cluster or managed services like Upstash for high availability.

​
Database (Supabase/PostgreSQL)

Responsibilities:
  • Store conversations, messages, and state
  • User authentication and authorization
  • File metadata and references
Scaling: Managed by Supabase or your PostgreSQL provider.

​
Running Modes

​
In-Process Mode

USE_JOB_QUEUE=false bun run start
When to use: Development, low-traffic deploymentsPros: Simple setup, no Redis requiredCons: Cannot scale horizontally, jobs block API server

​
Queue Mode

# Terminal 1: API Server
USE_JOB_QUEUE=true bun run start

# Terminal 2: Worker
USE_JOB_QUEUE=true bun run worker
When to use: Production deployments, high-traffic applicationsPros: Horizontal scaling, fault tolerance, graceful job handlingCons: Requires Redis infrastructure

​
Environment Requirements

​
Required

​
OPENAI_API_KEY
string
required
OpenAI API key for LLM models (or use alternative providers)
​
SUPABASE_URL
string
required
Supabase project URL for database access
​
SUPABASE_ANON_KEY
string
required
Supabase anonymous key for client authentication

​
Queue Mode

​
USE_JOB_QUEUE
boolean
default:"false"
Enable BullMQ job queue (required for production)
​
REDIS_URL
string
Redis connection URL (e.g., redis://localhost:6379)

​
Optional

​
BIOAGENTS_SECRET
string
JWT signing key for authentication
​
AUTH_MODE
string
default:"none"
Authentication mode: none or jwt

​
Resource Requirements

​
API Server

TrafficCPUMemoryInstances
Light (< 10 users)1 core512MB1
Medium (10-50 users)2 cores1GB2
Heavy (50+ users)4 cores2GB3+

​
Worker

WorkloadCPUMemoryWorkers
Light (< 10 jobs/hr)1 core1GB2
Medium (10-50 jobs/hr)2 cores2GB4
Heavy (50+ jobs/hr)4 cores4GB8+
Deep research jobs can consume significant memory (500MB-1GB per job). Size worker memory accordingly.

​
Redis

ScenarioMemoryConcurrent Jobs
Development256MB~50
Light Production512MB~100
Medium Production1GB~500
Heavy Production2GB+1000+

​
Health Checks

BioAgents provides a health endpoint for monitoring: 
curl http://localhost:3000/api/health
Response: 
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "jobQueue": {
    "enabled": true,
    "redis": "connected"
  }
}

​
Monitoring

​
Bull Board Dashboard

Access the job queue dashboard at /admin/queues when queue mode is enabled:
  • View queue status and metrics
  • Inspect job data and results
  • Retry failed jobs
  • Pause/resume queues

​
Logs

BioAgents uses structured logging with Pino: 
# View API server logs
docker logs -f bioagents-api

# View worker logs
docker logs -f bioagents-worker

# Filter by level
docker logs bioagents-api | grep '"level":50'  # errors only

​
Next Steps

Docker Setup

Learn how to deploy with docker-compose

Job Queue

Configure BullMQ for reliable job processing

Build docs developers (and LLMs) love

Get started for freeTalk to us