Skip to content

Configuration

Jump to bottom
Ömer Tarık Yılmaz edited this page Apr 5, 2026 · 1 revision

Configuration

White-Ops is configured primarily through environment variables defined in the .env file. This page provides a complete reference for every variable.

Table of Contents

Full .env Reference

General

Variable Type Default Description
APP_NAME string white-ops Display name for the platform
APP_ENV string production Environment: production, development, staging
SECRET_KEY string (required) Application secret key. Must be a random string of at least 32 characters. Used for general encryption.
DEBUG boolean false Enable debug mode. Set to true for development only. Enables verbose logging and stack traces.

Database (PostgreSQL)

Variable Type Default Description
POSTGRES_HOST string postgres PostgreSQL hostname. Use postgres for Docker, or an IP/hostname for external databases.
POSTGRES_PORT integer 5432 PostgreSQL port
POSTGRES_DB string whiteops Database name
POSTGRES_USER string whiteops Database username
POSTGRES_PASSWORD string (required) Database password. Must be set before first run.

Connection string: Assembled as postgresql+asyncpg://{user}:{password}@{host}:{port}/{db}

Redis

Variable Type Default Description
REDIS_HOST string redis Redis hostname. Use redis for Docker.
REDIS_PORT integer 6379 Redis port
REDIS_PASSWORD string (required) Redis authentication password

Connection string: Assembled as redis://:{password}@{host}:{port}/0

MinIO (S3-Compatible File Storage)

Variable Type Default Description
MINIO_ROOT_USER string whiteops MinIO access key (username)
MINIO_ROOT_PASSWORD string (required) MinIO secret key. Must be at least 8 characters.
MINIO_ENDPOINT string minio:9000 MinIO API endpoint
MINIO_BUCKET string whiteops-files Default bucket name for file storage

LLM Providers

Variable Type Default Description
ANTHROPIC_API_KEY string (empty) Anthropic Claude API key. Starts with sk-ant-.
OPENAI_API_KEY string (empty) OpenAI API key. Starts with sk-.
GOOGLE_API_KEY string (empty) Google Gemini API key
OLLAMA_BASE_URL string http://host.docker.internal:11434 Ollama API endpoint. Use host.docker.internal to reach Ollama running on the Docker host.
DEFAULT_LLM_PROVIDER string anthropic Default LLM provider: anthropic, openai, google, ollama
DEFAULT_LLM_MODEL string claude-sonnet-4-20250514 Default model identifier for the selected provider

At least one LLM provider must be configured with a valid API key (except Ollama, which needs no key).

Authentication

Variable Type Default Description
JWT_SECRET_KEY string (required) Secret key for signing JWT tokens. Must be a random string, different from SECRET_KEY.
JWT_ALGORITHM string HS256 JWT signing algorithm. HS256 is recommended.
JWT_ACCESS_TOKEN_EXPIRE_MINUTES integer 1440 Token lifetime in minutes. Default is 24 hours. Reduce for higher security.
ADMIN_EMAIL string admin@whiteops.local Email for the initial admin account, created on first run.
ADMIN_PASSWORD string (required) Password for the initial admin account.

Internal Mail

Variable Type Default Description
MAIL_SERVER_HOST string mail Internal mail server hostname. Use mail for Docker.
MAIL_SERVER_PORT integer 8025 Internal mail server port
MAIL_DOMAIN string whiteops.local Domain for internal agent email addresses (e.g., agent@whiteops.local)

External Email (Optional)

Variable Type Default Description
SMTP_HOST string (empty) External SMTP server hostname
SMTP_PORT integer 587 SMTP port (587 for STARTTLS, 465 for SSL)
SMTP_USER string (empty) SMTP authentication username
SMTP_PASSWORD string (empty) SMTP authentication password
SMTP_FROM string (empty) Default "From" address for outbound email
IMAP_HOST string (empty) IMAP server hostname for reading email
IMAP_PORT integer 993 IMAP port (993 for SSL)
IMAP_USER string (empty) IMAP authentication username
IMAP_PASSWORD string (empty) IMAP authentication password

Worker

Variable Type Default Description
WORKER_NAME string worker-01 Display name for this worker. Must be unique across the fleet.
WORKER_MAX_AGENTS integer 5 Maximum number of concurrent agents this worker can run. Scale based on CPU and RAM.
MASTER_URL string http://server:8000 URL of the master API server. Use http://server:8000 in Docker, or the master's IP/hostname for remote workers.

Worker-specific settings (used by worker/agent/config.py):

Variable Type Default Description
heartbeat_interval integer 30 Seconds between heartbeat messages to the master

Monitoring (Optional)

Variable Type Default Description
PROMETHEUS_ENABLED boolean true Enable Prometheus metrics endpoint
GRAFANA_ADMIN_PASSWORD string (required if monitoring) Grafana admin dashboard password

Network

Variable Type Default Description
SERVER_PORT integer 8000 Port to expose the API server on the host
WEB_PORT integer 3000 Port to expose the admin panel on the host
CORS_ORIGINS string http://localhost:3000 Comma-separated list of allowed CORS origins. Set to your actual frontend domain in production.

Settings API Categories

Settings can also be modified at runtime via the Settings API (PATCH /api/v1/settings). These are stored in the database and override environment defaults.

Category Settings Description
llm default_provider, default_model LLM provider and model selection
email mail_domain, smtp_host, smtp_port, etc. Email configuration
security jwt_expire_minutes, rate_limit Security parameters
general app_name, debug General application settings
notifications task_completion, worker_alerts, system_alerts Notification preferences
storage minio_endpoint, minio_bucket, max_file_size, retention_days File storage settings

See API-Reference#settings for full API details.

LLM Provider Configuration

Anthropic (Claude)

ANTHROPIC_API_KEY=sk-ant-api03-...
DEFAULT_LLM_PROVIDER=anthropic
DEFAULT_LLM_MODEL=claude-sonnet-4-20250514

Supported models: claude-sonnet-4-20250514, claude-opus-4-20250514, claude-haiku-235-20241022, and other Anthropic models.

OpenAI (GPT)

OPENAI_API_KEY=sk-...
DEFAULT_LLM_PROVIDER=openai
DEFAULT_LLM_MODEL=gpt-4o

Supported models: gpt-4o, gpt-4o-mini, gpt-4-turbo, and other OpenAI chat models.

Google (Gemini)

GOOGLE_API_KEY=AIza...
DEFAULT_LLM_PROVIDER=google
DEFAULT_LLM_MODEL=gemini-2.0-flash

Model names are mapped through LiteLLM as gemini/{model}.

Ollama (Local)

OLLAMA_BASE_URL=http://host.docker.internal:11434
DEFAULT_LLM_PROVIDER=ollama
DEFAULT_LLM_MODEL=llama3.2

No API key required. Ollama must be running and accessible. Model names are mapped as ollama/{model}.

To install and run Ollama:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2
ollama serve

Per-Agent Override

Individual agents can use a different provider/model than the default. Set this when creating or editing an agent in the admin panel or via the API.

SMTP Configuration

To enable external email (sending email to real addresses outside the platform):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=noreply@yourcompany.com

For receiving external email:

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your-email@gmail.com
IMAP_PASSWORD=your-app-password

Note: For Gmail, use an App Password (not your regular password). Enable "Less secure app access" or generate an App Password in Google Account settings.

Redis Configuration

Redis serves as a cache, pub/sub message queue, and task queue.

REDIS_HOST=redis        # Docker service name, or IP for external Redis
REDIS_PORT=6379
REDIS_PASSWORD=your-strong-password

External Redis

To use an external Redis instance (e.g., AWS ElastiCache, Redis Cloud):

REDIS_HOST=your-redis-host.example.com
REDIS_PORT=6379
REDIS_PASSWORD=your-external-redis-password

Remove the redis service from docker-compose.yml if using an external instance.

PostgreSQL Configuration

PostgreSQL is the primary persistent data store.

POSTGRES_HOST=postgres   # Docker service name, or IP for external DB
POSTGRES_PORT=5432
POSTGRES_DB=whiteops
POSTGRES_USER=whiteops
POSTGRES_PASSWORD=your-strong-password

External PostgreSQL

To use an external PostgreSQL instance (e.g., AWS RDS, Google Cloud SQL):

POSTGRES_HOST=your-db-host.example.com
POSTGRES_PORT=5432
POSTGRES_DB=whiteops
POSTGRES_USER=whiteops
POSTGRES_PASSWORD=your-external-db-password

Remove the postgres service from docker-compose.yml if using an external instance.

Migrations

Database schema changes are managed via Alembic:

# Apply all pending migrations
make migrate

# Create a new migration
make migrate-create MSG="add new column"

MinIO Configuration

MinIO provides S3-compatible object storage for files uploaded by users and generated by agents.

MINIO_ROOT_USER=whiteops
MINIO_ROOT_PASSWORD=your-strong-password-min-8-chars
MINIO_ENDPOINT=minio:9000
MINIO_BUCKET=whiteops-files

MinIO Console

The MinIO web console is available at http://localhost:9001 for managing buckets and files directly.

External S3

To use AWS S3 or another S3-compatible service:

MINIO_ENDPOINT=s3.amazonaws.com
MINIO_ROOT_USER=your-aws-access-key
MINIO_ROOT_PASSWORD=your-aws-secret-key
MINIO_BUCKET=your-s3-bucket-name

Remove the minio service from docker-compose.yml if using external object storage.

Clone this wiki locally