Configuration

Environment variables and configuration options for Airbeeps.

TIP

Most configuration happens through the Admin UI after first launch. This page covers environment variables and configuration files needed before starting the server.

Configuration Priority

Airbeeps supports multiple configuration sources, applied in this priority order (highest to lowest):

1. Environment variables (AIRBEEPS_*)
2. .env file
3. Environment-specific YAML (settings.{env}.yaml)
4. Base YAML (settings.yaml)
5. Hardcoded defaults

Core Settings

AIRBEEPS_SECRET_KEY

Required for production. Used for JWT token signing and session security.

# Generate a secure key
openssl rand -hex 32

Set in .env:

AIRBEEPS_SECRET_KEY=your-generated-key-here

WARNING

The default value is change-me-in-production. The server will warn you on startup if you haven't changed it.

AIRBEEPS_DATABASE_URL

Database connection string. Defaults to async SQLite in the data directory.

Default: sqlite+aiosqlite:///./data/airbeeps.db

PostgreSQL example:

AIRBEEPS_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/airbeeps

AIRBEEPS_DATA_ROOT

Base directory for storing uploaded files, database, and vector store data.

Default: data

AIRBEEPS_DATA_ROOT=/var/lib/airbeeps

AIRBEEPS_ENVIRONMENT

Environment mode: development or production.

Default: development

In development mode, API documentation is auto-enabled. In production, it's disabled by default.

LLM Provider Settings

Configure default provider credentials via environment variables, or set them in the Admin UI.

OpenAI

OPENAI_API_KEY=sk-...

Anthropic

ANTHROPIC_API_KEY=sk-ant-...

Google Gemini

GOOGLE_API_KEY=...

Vector Store Settings

AIRBEEPS_VECTOR_STORE_TYPE

Which vector store to use: qdrant, chromadb, pgvector, or milvus.

Default: qdrant

Qdrant (default)

AIRBEEPS_VECTOR_STORE_TYPE=qdrant
AIRBEEPS_QDRANT_URL=http://localhost:6333
AIRBEEPS_QDRANT_API_KEY=          # Optional
AIRBEEPS_QDRANT_PREFER_GRPC=true
AIRBEEPS_QDRANT_PERSIST_DIR=qdrant  # Relative to DATA_ROOT (for local/embedded mode)

ChromaDB

AIRBEEPS_VECTOR_STORE_TYPE=chromadb
AIRBEEPS_CHROMA_SERVER_HOST=       # Empty = embedded mode
AIRBEEPS_CHROMA_SERVER_PORT=8500
AIRBEEPS_CHROMA_PERSIST_DIR=chroma  # Relative to DATA_ROOT

PGVector

AIRBEEPS_VECTOR_STORE_TYPE=pgvector
AIRBEEPS_PGVECTOR_CONNECTION_STRING=  # Uses DATABASE_URL if empty
AIRBEEPS_PGVECTOR_SCHEMA=public

Milvus

AIRBEEPS_VECTOR_STORE_TYPE=milvus
AIRBEEPS_MILVUS_URI=http://localhost:19530
AIRBEEPS_MILVUS_TOKEN=
AIRBEEPS_MILVUS_DB_NAME=default

File Storage Settings

AIRBEEPS_FILE_STORAGE_BACKEND

Storage backend: local or s3.

Default: local

Local storage

AIRBEEPS_FILE_STORAGE_BACKEND=local
AIRBEEPS_LOCAL_STORAGE_ROOT=files  # Relative to DATA_ROOT

S3 / MinIO storage

AIRBEEPS_FILE_STORAGE_BACKEND=s3
AIRBEEPS_S3_ENDPOINT_URL=http://minio:9000
AIRBEEPS_S3_EXTERNAL_ENDPOINT_URL=http://localhost:9000
AIRBEEPS_S3_ACCESS_KEY_ID=minioadmin
AIRBEEPS_S3_SECRET_ACCESS_KEY=minioadmin
AIRBEEPS_S3_BUCKET_NAME=airbeeps
AIRBEEPS_S3_REGION=us-east-1
AIRBEEPS_S3_USE_SSL=false

Email Settings

AIRBEEPS_MAIL_ENABLED=false
AIRBEEPS_MAIL_SERVER=smtp.gmail.com
AIRBEEPS_MAIL_PORT=587
AIRBEEPS_MAIL_USERNAME=your-email@gmail.com
AIRBEEPS_MAIL_PASSWORD=your-app-password
AIRBEEPS_MAIL_STARTTLS=true
AIRBEEPS_MAIL_SSL_TLS=false
AIRBEEPS_MAIL_FROM=noreply@airbeeps.com

Auth Settings

Token configuration

Setting	Default	Description
ACCESS_TOKEN_LIFETIME_SECONDS	1800 (30 min)	Access token expiry
REFRESH_TOKEN_LIFETIME_SECONDS	2592000 (30 days)	Refresh token expiry
REFRESH_TOKEN_ROTATION_ENABLED	true	Rotate refresh tokens on use
REFRESH_TOKEN_MAX_PER_USER	5	Max active refresh tokens per user

Account lockout (brute force protection)

Setting	Default	Description
ACCOUNT_LOCKOUT_MAX_ATTEMPTS	5	Max failed login attempts
ACCOUNT_LOCKOUT_DURATION_MINUTES	15	Lockout duration

OAuth settings

AIRBEEPS_OAUTH_CREATE_USER_WITHOUT_EMAIL=true
AIRBEEPS_OAUTH_REQUIRE_EMAIL_VERIFICATION=false

RAG Feature Flags

Setting	Default	Description
RAG_ENABLE_HYBRID_SEARCH	true	Enable BM25 + dense fusion
RAG_ENABLE_RERANKING	true	Enable cross-encoder reranking
RAG_RERANKER_MODEL	BAAI/bge-reranker-v2-m3	Reranker model
RAG_RERANKER_TOP_N	5	Results after reranking
RAG_ENABLE_HIERARCHICAL	true	Enable hierarchical chunking
RAG_ENABLE_SEMANTIC_CHUNKING	true	Enable semantic chunking
RAG_QUERY_TRANSFORM_TYPE	multi_query	Query transform: none, hyde, multi_query, step_back

Agent & MCP Settings

AIRBEEPS_AGENT_MAX_ITERATIONS=10
AIRBEEPS_AGENT_TIMEOUT_SECONDS=300
AIRBEEPS_AGENT_ENABLE_MEMORY=false
AIRBEEPS_MCP_ENABLED=false
AIRBEEPS_MCP_SERVERS_CONFIG_PATH=/app/mcp_servers.json

Redis Settings (optional)

Redis is optional. When disabled, in-memory caching is used.

AIRBEEPS_REDIS_ENABLED=false
AIRBEEPS_REDIS_URL=redis://localhost:6379/0
AIRBEEPS_REDIS_PASSWORD=

Install with: pip install airbeeps[redis]

Celery Settings (optional)

Celery is optional. When disabled, in-process async tasks are used.

AIRBEEPS_CELERY_ENABLED=false
AIRBEEPS_CELERY_BROKER_URL=redis://localhost:6379/1
AIRBEEPS_CELERY_RESULT_BACKEND=redis://localhost:6379/2
AIRBEEPS_CELERY_WORKER_CONCURRENCY=4

Install with: pip install airbeeps[celery]

Observability Settings

AIRBEEPS_TRACING_ENABLED=true
AIRBEEPS_TRACING_BACKEND=local    # local | otlp | jaeger | console | none
AIRBEEPS_TRACING_ENDPOINT=        # OTLP/Jaeger endpoint URL
AIRBEEPS_TRACING_SAMPLE_RATE=1.0
AIRBEEPS_TRACING_REDACT_PII=true  # Redact PII from traces (GDPR)
AIRBEEPS_TRACING_ADMIN_ONLY=true
AIRBEEPS_TRACING_RETENTION_DAYS=30

Development Settings

AIRBEEPS_LOG_LEVEL

Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL.

Default: INFO

AIRBEEPS_TEST_MODE

When enabled, all external LLM/embedding calls are replaced with deterministic fakes.

Default: false

YAML Configuration

For complex deployments, you can use YAML configuration files instead of (or alongside) environment variables. Place them in the config/ directory inside the backend package:

• settings.yaml — Base configuration
• settings.development.yaml — Development overrides
• settings.production.yaml — Production overrides
• settings.docker.yaml — Docker-specific overrides

The active environment is determined by AIRBEEPS_CONFIG_ENV or AIRBEEPS_ENVIRONMENT.

Example settings.yaml:

vector_store:
  type: qdrant
  qdrant:
    url: http://localhost:6333
    prefer_grpc: true

rag:
  features:
    enable_hybrid_search: true
    enable_reranking: true
  reranker:
    model: BAAI/bge-reranker-v2-m3
    top_n: 5

agent:
  max_iterations: 10
  timeout_seconds: 300

Environment variables always take precedence over YAML values.

Example .env file

# Required
AIRBEEPS_SECRET_KEY=your-secret-key-here

# Database
AIRBEEPS_DATABASE_URL=sqlite+aiosqlite:///./data/airbeeps.db
AIRBEEPS_DATA_ROOT=data

# Environment
AIRBEEPS_ENVIRONMENT=development

# LLM Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Vector Store
AIRBEEPS_VECTOR_STORE_TYPE=qdrant
AIRBEEPS_QDRANT_PERSIST_DIR=qdrant

# File Storage
AIRBEEPS_FILE_STORAGE_BACKEND=local

# Logging
AIRBEEPS_LOG_LEVEL=INFO

Runtime Configuration

Most settings can be configured through the Admin UI after startup:

• Default models per provider
• Embedding models
• Chunking parameters
• Retrieval strategies
• System prompts
• Agent and MCP settings

Changes made in the UI are stored in the database and persist across restarts.