Configuration - Airweave

Environment File

Airweave uses environment variables for configuration. Copy .env.example to .env and customize:

cp .env.example .env

The start.sh script automatically generates required secrets if they’re missing.

Required Variables

These variables must be set for Airweave to function:

Encryption & Security

ENCRYPTION_KEY

string

required

Base64-encoded 32-byte key for encrypting sensitive data (API keys, OAuth tokens)Auto-generated by start.sh using:

openssl rand -base64 32

STATE_SECRET

string

required

Secret for OAuth state parameter signingAuto-generated by start.sh using:

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'

Embedding Configuration

All three embedding variables are required. The application will not start without them.

DENSE_EMBEDDER

string

required

Dense embedding model for semantic searchOptions:

openai_text_embedding_3_small - Up to 1536 dimensions (requires OPENAI_API_KEY)
openai_text_embedding_3_large - Up to 3072 dimensions (requires OPENAI_API_KEY)
mistral_embed - Fixed 1024 dimensions (requires MISTRAL_API_KEY)
local_minilm - Fixed 384 dimensions (requires local embeddings service)

Default: openai_text_embedding_3_small

EMBEDDING_DIMENSIONS

integer

required

Vector dimensions matching the chosen embedderMust match your DENSE_EMBEDDER:

OpenAI small: 1536
OpenAI large: 3072
Mistral: 1024
Local MiniLM: 384

Default: 1536

Changing this after data is indexed requires re-indexing all documents.

SPARSE_EMBEDDER

string

required

Sparse embedding model for keyword search (BM25)Options:

fastembed_bm25 - Fast BM25 implementation (no API key needed)

Default: fastembed_bm25

Database Configuration

PostgreSQL

POSTGRES_HOST

string

default:"localhost"

PostgreSQL server hostnameDocker Compose: localhost (mapped port)Kubernetes: Service name (e.g., postgres-service)

POSTGRES_PORT

integer

default:"5432"

PostgreSQL server port

POSTGRES_USER

string

default:"airweave"

PostgreSQL username

POSTGRES_PASSWORD

string

default:"airweave1234!"

PostgreSQL password

Change this in production!

POSTGRES_DB

string

default:"airweave"

PostgreSQL database name

POSTGRES_SSLMODE

string

default:"prefer"

SSL mode for PostgreSQL connectionOptions: disable, allow, prefer, require, verify-ca, verify-full

Redis

REDIS_HOST

string

default:"localhost"

Redis server hostname

REDIS_PORT

integer

default:"6379"

Redis server port

Storage Configuration

Airweave supports multiple storage backends for file attachments:

Backend Selection

STORAGE_BACKEND

string

default:"filesystem"

Storage backend typeOptions:

filesystem - Local or PVC storage (default for local/test)
azure - Azure Blob Storage (default for dev/prd with Azure)
aws - AWS S3 or S3-compatible storage
gcp - Google Cloud Storage

Auto-resolution: If not set, defaults based on ENVIRONMENT:

local or test → filesystem
dev or prd → azure

Filesystem Storage

STORAGE_PATH

string

default:"./local_storage"

Local filesystem path for file storageDevelopment: ./local_storage (relative to project root)Kubernetes: /data/airweave-storage (PVC mount point)Debugging tip: Use /tmp/airweave_local_storage to avoid uvicorn reload issues

SKIP_AZURE_STORAGE

boolean

default:"true"

Skip Azure Blob Storage initialization (set by start.sh)

Azure Blob Storage

STORAGE_AZURE_ACCOUNT

string

Azure Storage account nameExample: airweavestorage

STORAGE_AZURE_CONTAINER

string

default:"raw"

Azure Blob container name

STORAGE_AZURE_PREFIX

string

Optional path prefix within container

AWS S3 Storage

STORAGE_AWS_BUCKET

string

S3 bucket nameExample: airweave-production

STORAGE_AWS_REGION

string

AWS regionExample: us-east-1

STORAGE_AWS_PREFIX

string

Optional path prefix within bucket

STORAGE_AWS_ENDPOINT_URL

string

Custom S3 endpoint for MinIO, LocalStack, etc.Example: http://minio:9000

AWS_ACCESS_KEY_ID

string

AWS access key (or use IAM roles in production)

AWS_SECRET_ACCESS_KEY

string

AWS secret key (or use IAM roles in production)

GCP Cloud Storage

STORAGE_GCP_BUCKET

string

GCS bucket name

STORAGE_GCP_PROJECT

string

GCP project ID

STORAGE_GCP_PREFIX

string

Optional path prefix within bucket

Authentication

Local Authentication

AUTH_ENABLED

boolean

default:"false"

Enable authentication systemDevelopment: false (single-user mode)Production: true (requires Auth0 or similar)

FIRST_SUPERUSER

string

default:"admin@example.com"

Default admin user email (when AUTH_ENABLED=false)

FIRST_SUPERUSER_PASSWORD

string

default:"admin"

Default admin password

Change this in production!

Auth0 Configuration

Required when AUTH_ENABLED=true

AUTH0_DOMAIN

string

Auth0 tenant domainExample: your-tenant.auth0.com

AUTH0_AUDIENCE

string

Auth0 API audience identifierExample: https://api.airweave.ai

AUTH0_RULE_NAMESPACE

string

Namespace for custom claims in Auth0 tokensExample: https://airweave.ai

Temporal Configuration

TEMPORAL_HOST

string

default:"localhost"

Temporal server hostname

TEMPORAL_PORT

integer

default:"7233"

Temporal gRPC port

TEMPORAL_NAMESPACE

string

default:"default"

Temporal namespace for workflows

TEMPORAL_TASK_QUEUE

string

default:"airweave-sync-queue"

Task queue name for sync workers

Vespa Configuration

VESPA_URL

string

default:"http://localhost"

Vespa server URL (without port)

VESPA_PORT

integer

default:"8081"

Vespa document API port

Embeddings Services

Local Embeddings

TEXT2VEC_INFERENCE_URL

string

default:"http://localhost:9878"

Local embedding service URLDocker: http://text2vec-transformers:8080Only used when DENSE_EMBEDDER=local_minilm

API Keys

OPENAI_API_KEY

string

OpenAI API key for embeddings and LLM featuresRequired for:

openai_text_embedding_3_small
openai_text_embedding_3_large
File content extraction
Natural language search

ANTHROPIC_API_KEY

string

Anthropic API key (for future features)

MISTRAL_API_KEY

string

Mistral API key for embeddingsRequired for: mistral_embed embedder

Webhook Configuration (Svix)

SVIX_URL

string

default:"http://localhost:8071"

Svix webhook server URL

SVIX_JWT_SECRET

string

Secret for signing Svix JWTs (must be ≥32 bytes)Default: default_signing_secret_change_me!

Change this in production!

SVIX_AUTH_TOKEN

string

Optional authentication token for Svix API

Application Settings

Environment

ENVIRONMENT

string

default:"local"

Deployment environmentOptions: local, test, dev, prdAffects:

Default storage backend
Logging verbosity
Error reporting

LOCAL_DEVELOPMENT

boolean

default:"false"

Enable development mode featuresWhen true:

Hot reload enabled
Verbose logging
CORS relaxed

Docker: Automatically set to true

LOCAL_CURSOR_DEVELOPMENT

boolean

default:"false"

Special mode for Cursor IDE integration

Logging

LOG_LEVEL

string

default:"INFO"

Python logging levelOptions: DEBUG, INFO, WARNING, ERROR, CRITICAL

Database Management

RUN_ALEMBIC_MIGRATIONS

boolean

default:"true"

Automatically run database migrations on startupRecommended: true for most deploymentsSet to false only if managing migrations externally

RUN_DB_SYNC

boolean

default:"true"

Synchronize database state on startup

Features

CODE_SUMMARIZER_ENABLED

boolean

default:"false"

Enable AI code summarization for developer tools

STRIPE_ENABLED

boolean

default:"false"

Enable Stripe payment integration (for managed hosting)

URLs

API_FULL_URL

string

Full public URL for the API (for webhooks and OAuth callbacks)Example: https://api.yourdomain.com

APP_FULL_URL

string

Full public URL for the frontendExample: https://app.yourdomain.com

ADDITIONAL_CORS_ORIGINS

string

Comma-separated list of additional CORS originsExample: https://custom-ui.com,https://staging.example.com

Frontend

FRONTEND_LOCAL_DEVELOPMENT_PORT

integer

default:"8080"

Port for frontend UI

Miscellaneous

PROJECT_NAME

string

default:"Airweave"

Project display name

DOCLING_BASE_URL

string

Optional secondary OCR provider for document processing

Test Configuration

These variables are only used for integration tests:

AWS S3 Tests

STORAGE_TEST_AWS_BUCKET

string

default:"airweave-storage-backend-tests"

S3 bucket for storage backend tests

STORAGE_TEST_AWS_REGION

string

default:"us-east-1"

AWS region for tests

GCP Storage Tests

STORAGE_TEST_GCP_BUCKET

string

default:"airweave-storage-backend-tests"

GCS bucket for tests

STORAGE_TEST_GCP_PROJECT

string

default:"airweave-production"

GCP project for tests

Azure Blob Tests

STORAGE_TEST_AZURE_ACCOUNT

string

default:"airweavecoredevstorage"

Azure storage account for tests

STORAGE_TEST_AZURE_CONTAINER

string

default:"backend-tests"

Azure container for tests

Configuration Examples

Development (Local Embeddings)

.env

# Auto-generated secrets
ENCRYPTION_KEY="<generated>"
STATE_SECRET="<generated>"

# Database (defaults)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=airweave
POSTGRES_PASSWORD=airweave1234!
POSTGRES_DB=airweave

# Embeddings (local)
DENSE_EMBEDDER=local_minilm
EMBEDDING_DIMENSIONS=384
SPARSE_EMBEDDER=fastembed_bm25
TEXT2VEC_INFERENCE_URL=http://localhost:9878

# Storage
STORAGE_BACKEND=filesystem
STORAGE_PATH=./local_storage
SKIP_AZURE_STORAGE=true

# Auth (disabled for dev)
AUTH_ENABLED=false
FIRST_SUPERUSER=admin@example.com
FIRST_SUPERUSER_PASSWORD=admin

# Environment
ENVIRONMENT=local
LOCAL_DEVELOPMENT=true
LOG_LEVEL=INFO

Production (OpenAI Embeddings + Cloud Storage)

.env

# Security (regenerate all!)
ENCRYPTION_KEY="<strong-random-key>"
STATE_SECRET="<strong-random-secret>"
SVIX_JWT_SECRET="<strong-random-secret>"

# Database (managed service)
POSTGRES_HOST=postgres.example.com
POSTGRES_PORT=5432
POSTGRES_USER=airweave
POSTGRES_PASSWORD="<strong-password>"
POSTGRES_DB=airweave
POSTGRES_SSLMODE=require

# Redis (managed service)
REDIS_HOST=redis.example.com
REDIS_PORT=6379

# Embeddings (OpenAI)
DENSE_EMBEDDER=openai_text_embedding_3_small
EMBEDDING_DIMENSIONS=1536
SPARSE_EMBEDDER=fastembed_bm25
OPENAI_API_KEY="sk-..."

# Storage (AWS S3)
STORAGE_BACKEND=aws
STORAGE_AWS_BUCKET=airweave-production
STORAGE_AWS_REGION=us-east-1
# Use IAM roles instead of access keys in production

# Auth (enabled)
AUTH_ENABLED=true
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://api.yourdomain.com
AUTH0_RULE_NAMESPACE=https://yourdomain.com

# URLs
API_FULL_URL=https://api.yourdomain.com
APP_FULL_URL=https://app.yourdomain.com

# Environment
ENVIRONMENT=prd
LOCAL_DEVELOPMENT=false
LOG_LEVEL=WARNING

Kubernetes (Mistral Embeddings + GCP Storage)

.env

# Security (loaded from Kubernetes Secrets)
ENCRYPTION_KEY="${ENCRYPTION_KEY}"
STATE_SECRET="${STATE_SECRET}"

# Database (Kubernetes service)
POSTGRES_HOST=postgres-service
POSTGRES_PORT=5432
POSTGRES_USER=airweave
POSTGRES_PASSWORD="${POSTGRES_PASSWORD}"
POSTGRES_DB=airweave

# Redis (Kubernetes service)
REDIS_HOST=redis-service
REDIS_PORT=6379

# Embeddings (Mistral)
DENSE_EMBEDDER=mistral_embed
EMBEDDING_DIMENSIONS=1024
SPARSE_EMBEDDER=fastembed_bm25
MISTRAL_API_KEY="${MISTRAL_API_KEY}"

# Storage (GCP with Workload Identity)
STORAGE_BACKEND=gcp
STORAGE_GCP_BUCKET=airweave-production
STORAGE_GCP_PROJECT=your-project-id
# No credentials needed - uses Workload Identity

# Temporal (Kubernetes service)
TEMPORAL_HOST=temporal-service
TEMPORAL_PORT=7233

# Vespa (Kubernetes service)
VESPA_URL=http://vespa-service
VESPA_PORT=8081

# Auth
AUTH_ENABLED=true
AUTH0_DOMAIN="${AUTH0_DOMAIN}"
AUTH0_AUDIENCE="${AUTH0_AUDIENCE}"

# Environment
ENVIRONMENT=prd
LOG_LEVEL=INFO
RUN_ALEMBIC_MIGRATIONS=true

Security Best Practices

Never commit .env files to version control!

Rotate secrets regularly

Generate new values for:

ENCRYPTION_KEY
STATE_SECRET
SVIX_JWT_SECRET
Database passwords

Use secrets management

In production, load secrets from:

Kubernetes: Secrets, External Secrets Operator
AWS: Secrets Manager, Parameter Store
Azure: Key Vault
GCP: Secret Manager
HashiCorp: Vault

Use managed identity

For cloud storage, prefer:

AWS IAM Roles for Service Accounts (IRSA)
Azure Managed Identity / Workload Identity
GCP Workload Identity

Avoid hardcoding access keys.

Enable SSL/TLS

Set POSTGRES_SSLMODE=require
Use HTTPS for all external URLs
Configure TLS certificates for Redis if exposed

Restrict network access

Use private networks for database connections
Firewall rules for service-to-service communication
VPN or bastion hosts for admin access

Troubleshooting

Application won't start - missing embedding variables

Error: DENSE_EMBEDDER, EMBEDDING_DIMENSIONS, and SPARSE_EMBEDDER must all be setSolution: Set all three variables in .env:

DENSE_EMBEDDER=openai_text_embedding_3_small
EMBEDDING_DIMENSIONS=1536
SPARSE_EMBEDDER=fastembed_bm25

Dimension mismatch error

Error: Vespa schema expects different dimensionsSolution:

Ensure EMBEDDING_DIMENSIONS matches your DENSE_EMBEDDER

Recreate Vespa deployment:

docker compose down --volumes
./start.sh

Storage backend not working

Check:

Credentials are correct (access keys, service account)
Bucket/container exists and is accessible
Permissions allow read/write operations

Test connection:

docker exec airweave-backend \
  poetry run python -c "from airweave.utils.storage import get_storage_backend; get_storage_backend().list_files('test/')"

Database connection failures

Debug:

# Test from backend container
docker exec airweave-backend \
  poetry run python -c "from airweave.db.engine import get_session; next(get_session())"

# Check PostgreSQL logs
docker logs airweave-db

Common issues:

Wrong host/port
Incorrect credentials
SSL mode mismatch
Database not initialized

Next Steps

Deploy with Docker

Get started with Docker Compose deployment

Scale with Kubernetes

Production deployment on Kubernetes

Configure Connectors

Set up data source integrations

Advanced Features

Customize embeddings, chunking, and transformers

Getting Started

Core Features

Data Sources

Integrations

Self-Hosting

Advanced

Contributing

​Environment File

​Required Variables

​Encryption & Security

​Embedding Configuration

​Database Configuration

​PostgreSQL

​Redis

​Storage Configuration

​Backend Selection

​Filesystem Storage

​Azure Blob Storage

​AWS S3 Storage

​GCP Cloud Storage

​Authentication

​Local Authentication

​Auth0 Configuration

​Temporal Configuration

​Vespa Configuration

​Embeddings Services

​Local Embeddings

​API Keys

​Webhook Configuration (Svix)

​Application Settings

​Environment

​Logging

​Database Management

​Features

​URLs

​Frontend

​Miscellaneous

​Test Configuration

​AWS S3 Tests

​GCP Storage Tests

​Azure Blob Tests

​Configuration Examples

​Development (Local Embeddings)

​Production (OpenAI Embeddings + Cloud Storage)

​Kubernetes (Mistral Embeddings + GCP Storage)

​Security Best Practices

​Troubleshooting

​Next Steps

Deploy with Docker

Scale with Kubernetes

Configure Connectors

Advanced Features

Environment File

Required Variables

Encryption & Security

Embedding Configuration

Database Configuration

PostgreSQL

Redis

Storage Configuration

Backend Selection

Filesystem Storage

Azure Blob Storage

AWS S3 Storage

GCP Cloud Storage

Authentication

Local Authentication

Auth0 Configuration

Temporal Configuration

Vespa Configuration

Embeddings Services

Local Embeddings

API Keys

Webhook Configuration (Svix)

Application Settings

Environment

Logging

Database Management

Features

URLs

Frontend

Miscellaneous

Test Configuration

AWS S3 Tests

GCP Storage Tests

Azure Blob Tests

Configuration Examples

Development (Local Embeddings)

Production (OpenAI Embeddings + Cloud Storage)

Kubernetes (Mistral Embeddings + GCP Storage)

Security Best Practices

Troubleshooting

Next Steps