.env.example

# BackAI environment configuration.
#
# Copy this file to .env and fill in your values. Public docs use the BackAI
# name. Existing runtime/package variables intentionally keep the stable
# AF_STACK_* namespace to avoid breaking deploys and forks.

# ---------- Deployment mode ----------

# BackAI runs in one of two modes:
#
#   saas     (default) — multi-tenant. Auth (login) and billing are governed
#                        by their module flags below. This is what you deploy
#                        to run BackAI as a product with real customers.
#
#   personal           — single-user app. Auth AND billing are forced OFF:
#                        no login on either frontend, no paywall, no Stripe,
#                        no budget 402s. Everything runs under the built-in
#                        default tenant so the app is usable straight off the
#                        bat. Ideal for running BackAI just for yourself.
#
# Flip it any time (then restart): set AF_STACK_MODE below, or run
#   af-stack mode personal   /   af-stack mode saas
# Note: data written in personal mode is owned by the default tenant, so
# switching back to saas keeps that data under the default tenant.
AF_STACK_MODE=saas

# Individual module flags (ignored/overridden when AF_STACK_MODE=personal):
#   AF_STACK_MODULE_MULTI_TENANCY  — per-tenant auth + isolation (default false)
#   AF_STACK_MODULE_BILLING        — Stripe + budget paywall     (default true)
# AF_STACK_MODULE_MULTI_TENANCY=false
# AF_STACK_MODULE_BILLING=true

# ---------- Required ----------

# Postgres connection string for the suite
AF_STACK_DATABASE_URL=postgres://afstack:afstack@postgres:5432/afstack?sslmode=disable

# AgentField storage configuration (stateless, multi-replica safe)
AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_STORAGE_POSTGRES_URL=postgres://afstack:afstack@postgres:5432/agentfield?sslmode=disable
AGENTFIELD_STORAGE_POSTGRES_ENABLE_MEMORY_FALLBACK=false
AGENTFIELD_STORAGE_POSTGRES_ENABLE_DID_FALLBACK=false
AGENTFIELD_STORAGE_POSTGRES_ENABLE_VC_FALLBACK=false

# Customer-facing AgentField URL used by the dashboard for "View in
# AgentField" link-outs (run / DAG / step inspector). Leave commented in
# dev to fall back to the runtime's internal AgentField URL; set this in
# prod to the externally-reachable AgentField host so operators get a
# clickable link from the dashboard.
# AF_STACK_AGENTFIELD_PUBLIC_URL=http://localhost:8081

# Session signing secret (generate with: openssl rand -hex 32)
AF_STACK_AUTH_SECRET=change-me-to-a-real-secret

# Secrets vault KMS provider.
#
# env keeps the quickstart path: AF_STACK_KMS_KEY is a raw 32-byte hex
# data key. For production BYOK, set AF_STACK_KMS_PROVIDER to aws, gcp,
# or azure and provide a base64 encrypted data key instead.
AF_STACK_KMS_PROVIDER=env

# KMS key for env-provider secrets encryption. The value below is the
# runtime's well-known DEV SENTINEL (the same default docker-compose.yml
# uses): it boots with a deterministic dev key and logs a warning. Any
# other value that is not 32 hex-encoded bytes makes the runtime refuse to
# start, because a misconfigured key must never silently disable the vault.
# For anything beyond local dev, generate a real one: openssl rand -hex 32
AF_STACK_KMS_KEY=dev-secret-change-me

# Cloud BYOK providers unwrap this encrypted data key at runtime boot.
# The plaintext must be 32 bytes after cloud KMS decrypt/unwrap.
# AF_STACK_KMS_ENCRYPTED_DATA_KEY=
# AF_STACK_KMS_ENCRYPTED_DATA_KEY_FILE=

# AWS KMS BYOK
# AF_STACK_KMS_PROVIDER=aws
# AF_STACK_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/...
# AWS_REGION=us-east-1

# GCP Cloud KMS BYOK
# AF_STACK_KMS_PROVIDER=gcp
# AF_STACK_GCP_KMS_KEY_NAME=projects/.../locations/.../keyRings/.../cryptoKeys/...

# Azure Key Vault BYOK
# AF_STACK_KMS_PROVIDER=azure
# AF_STACK_AZURE_KEY_VAULT_URL=https://example.vault.azure.net/
# AF_STACK_AZURE_KMS_KEY_NAME=af-stack-secrets
# AF_STACK_AZURE_KMS_KEY_VERSION=
# AF_STACK_AZURE_KMS_ALGORITHM=RSA-OAEP-256

# ---------- LLM providers (set what you use) ----------
#
# BackAI runs a LiteLLM Proxy sidecar (image
# ghcr.io/berriai/litellm:main-stable) on port 4000. Every /api/v1/llm/*
# call from customers is forwarded there. You drop in a provider key
# here, the matching `model_list` entry in
# apps/backend/litellm-config.yaml activates, and 100+ models become
# usable without code changes.

# LLM gateway adapter selector: demo | litellm | remote. This picks WHICH
# backend answers /api/v1/llm/*. Validated at boot (unsupported value fails
# fast). Left unset, the runtime uses AF_STACK_DEMO_MODE below to choose
# between demo and litellm automatically.
#   demo    — deterministic no-key provider (offline demos + tests)
#   litellm — the LiteLLM Proxy sidecar (100+ real providers)
#   remote  — an out-of-process gateway speaking the remote protocol
# AF_STACK_LLM_GATEWAY_ADAPTER=litellm
#
# Remote gateway creds (only when AF_STACK_LLM_GATEWAY_ADAPTER=remote). Can
# also be set from the dashboard → Platform → Integrations; env wins.
# AF_STACK_LLM_REMOTE_URL=https://llm-adapter.example.com
# AF_STACK_LLM_REMOTE_TOKEN=

# First-run mode. "auto" uses the deterministic no-key demo provider when no
# provider key below is set, and switches to LiteLLM when you add a real key.
AF_STACK_DEMO_MODE=auto

# Recommended for quickstart: one OpenRouter key gets you many models.
# The sample agent picks a cheap-but-capable default model
# (qwen/qwen-2.5-72b-instruct, about $0.35/$0.40 per 1M tokens) so demos
# stay sub-cent. Override with SAMPLE_AGENT_MODEL=<provider>/<model>.
OPENROUTER_API_KEY=

# Or use providers directly:
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=
# GEMINI_API_KEY=
# MISTRAL_API_KEY=
# DEEPSEEK_API_KEY=
# GROQ_API_KEY=

# ──────────────── Multimodal (#14) — first-party adapters ────────────────
# Audio + image first-party adapters. Each adapter is excluded from the
# registry when its key is empty; models routed to it then return a
# clear 503 with "configure <ENV_VAR>".
#
#   /audio/speech (TTS):
#     openai/tts-1, openai/tts-1-hd → uses OPENAI_API_KEY via LiteLLM
#     elevenlabs/<model>            → uses ELEVENLABS_API_KEY
#     cartesia/<model>              → uses CARTESIA_API_KEY
#   /audio/transcriptions, /audio/translations (STT):
#     openai/whisper-1              → uses OPENAI_API_KEY via LiteLLM
#   /images/generations, /images/edits, /images/variations:
#     openai/dall-e-{2,3}, openai/gpt-image-1 → uses OPENAI_API_KEY via LiteLLM
#     flux/<model>                  → uses FAL_API_KEY (preferred) or REPLICATE_API_KEY
#     fal/<model>                   → uses FAL_API_KEY
#
# ELEVENLABS_API_KEY=
# CARTESIA_API_KEY=
# FAL_API_KEY=
# REPLICATE_API_KEY=

# LiteLLM sidecar internal auth — shared between the runtime and the
# LiteLLM container only. Customers never see this; they authenticate
# with their tenant API key one layer earlier. Override in production.
# LITELLM_MASTER_KEY=sk-litellm-dev

# LiteLLM sidecar URL the runtime forwards to. Default is the
# docker-compose service name; override for bare-metal/remote deploys.
# AF_STACK_LITELLM_URL=http://litellm:4000

# Gateway guardrails. Regex PII redaction is enabled by default for
# /api/v1/llm/* request/response text. Set AF_STACK_PII_PROVIDER=presidio
# and the Presidio URLs to use Presidio instead of the built-in regex
# redactor. Moderation block regexes are operator-owned and comma/newline
# separated.
# AF_STACK_GUARDRAILS_ENABLED=true
# AF_STACK_PII_REDACTION_ENABLED=true
# AF_STACK_PII_PROVIDER=regex
# AF_STACK_PRESIDIO_ANALYZER_URL=http://presidio-analyzer:3000
# AF_STACK_PRESIDIO_ANONYMIZER_URL=http://presidio-anonymizer:3000
# AF_STACK_MODERATION_ENABLED=true
# AF_STACK_MODERATION_BLOCK_PATTERNS=

# External port the LiteLLM sidecar binds on the host (for direct
# debugging via its admin UI). Internal traffic between runtime and
# LiteLLM uses Docker DNS and doesn't need this set.
# LITELLM_PORT=4000

# Override the sample agent's default model. Useful for testing pricing.
# Examples:
#   SAMPLE_AGENT_MODEL=openrouter/qwen/qwen-2.5-7b-instruct  (even cheaper)
#   SAMPLE_AGENT_MODEL=openai/gpt-4o-mini
#   SAMPLE_AGENT_MODEL=anthropic/claude-haiku-4-5-20251001
# SAMPLE_AGENT_MODEL=

# ---------- Object storage (MinIO by default) ----------

# Storage adapter selector: minio | s3 | remote. Defaults to minio.
#   minio  — local dev / self-hosted S3-compatible (uses AF_STACK_S3_* below)
#   s3     — AWS S3 / R2 / GCS / Azure Blob via the S3 API (AF_STACK_S3_* + creds)
#   remote — an out-of-process storage adapter speaking the remote protocol
# AF_STACK_S3_ADAPTER=minio
AF_STACK_S3_ENDPOINT=http://minio:9000
AF_STACK_S3_BUCKET=af-stack
AF_STACK_S3_ACCESS_KEY=minio
AF_STACK_S3_SECRET_KEY=minio-secret
AF_STACK_S3_REGION=us-east-1

# Remote storage adapter (only when AF_STACK_S3_ADAPTER=remote). Creds can
# also be set from the dashboard → Platform → Integrations (stored in the
# secrets vault); env wins when both are present.
# AF_STACK_STORAGE_REMOTE_URL=https://storage-adapter.example.com
# AF_STACK_STORAGE_REMOTE_TOKEN=

# ---------- Secrets store adapter ----------
#
# Selects WHERE secret values live (distinct from AF_STACK_KMS_PROVIDER
# above, which selects how the data key is wrapped):
#   vault  — (default) the built-in Postgres-backed AES-256-GCM vault
#   remote — an out-of-process secrets backend speaking the remote protocol
# This selector is validated at boot (an unsupported value fails fast).
# ROADMAP: the remote secrets adapter is selectable + capability-probed,
# but the server currently binds the concrete vault type, so a remote
# backend cannot yet fully back /api/v1/secrets end-to-end. Treat remote
# secrets as a known limitation until the server's secrets dependency is
# generalized to the Store interface.
# AF_STACK_SECRETS_ADAPTER=vault
#
# Remote secrets creds are ENV-ONLY (chicken-and-egg: the vault can't be
# used to configure its own backend, so these are read from env at boot).
# AF_STACK_SECRETS_REMOTE_URL=https://secrets-adapter.example.com
# AF_STACK_SECRETS_REMOTE_TOKEN=

# ---------- Notifications ----------
#
# Notification adapter selector: log | resend | slack | sms (alias twilio)
#   | push (alias fcm) | remote. Defaults to log.
# Channel creds below can also be set from the dashboard → Platform →
# Integrations (stored in the secrets vault); env wins when both are set.
# AF_STACK_NOTIFICATIONS_ADAPTER=log

# Email (Resend)
# RESEND_API_KEY=
# AF_STACK_NOTIFICATIONS_FROM=

# Slack (incoming webhook)
# AF_STACK_SLACK_WEBHOOK_URL=

# SMS (Twilio)
# AF_STACK_TWILIO_ACCOUNT_SID=
# AF_STACK_TWILIO_AUTH_TOKEN=
# AF_STACK_TWILIO_FROM_NUMBER=
# AF_STACK_TWILIO_BASE_URL=   # optional; override the Twilio API base URL

# Push (Firebase Cloud Messaging). AF_STACK_FCM_ACCESS_TOKEN is a short-lived
# OAuth access token — minting it from a service-account JSON is expected to
# be done at the boot/ops layer, not by BackAI.
# AF_STACK_FCM_PROJECT_ID=
# AF_STACK_FCM_ACCESS_TOKEN=
# AF_STACK_FCM_BASE_URL=      # optional; override the FCM API base URL

# Remote notifications adapter (only when AF_STACK_NOTIFICATIONS_ADAPTER=remote).
# ENV-ONLY. If the URL is empty the runtime falls back to the log adapter.
# AF_STACK_NOTIFICATIONS_ADAPTER_URL=https://notify-adapter.example.com
# AF_STACK_NOTIFICATIONS_ADAPTER_TOKEN=

# ---------- Optional integrations ----------

# ---------- Default operator account ----------
# Seeded on first boot so the operator console at http://localhost:33000 is
# usable immediately — no signup wizard (the console has no change-password
# page yet, so pick real values here). Seeding only runs while the operator
# table is empty, so changing these values after first boot has no effect (reset the
# Postgres volume to re-seed). Set AF_STACK_DEFAULT_OPERATOR_DISABLED=true to
# skip seeding entirely (e.g. when you provision operators another way).
# AF_STACK_DEFAULT_OPERATOR_EMAIL=operator@af-stack.local
# AF_STACK_DEFAULT_OPERATOR_PASSWORD=changeme123
# AF_STACK_DEFAULT_OPERATOR_NAME=Default Operator
# AF_STACK_DEFAULT_OPERATOR_DISABLED=false

# Auth adapter selector: better-auth (the only implementation today). The
# value is now validated at boot — an unsupported value fails fast instead
# of being silently ignored. There is one auth impl; this env exists so the
# selector is honest, not because a second backend ships yet.
# AF_STACK_AUTH_ADAPTER=better-auth

# Dashboard sign-in providers (better-auth). These are for humans signing
# into the operator console / customer app, not for agents acting as users.
# GOOGLE_CLIENT_ID=
# GOOGLE_CLIENT_SECRET=
#
# Enterprise SSO/SAML (#26): BackAI accepts OIDC here. For SAML
# customers, put Authentik in front as the self-hosted SAML-to-OIDC
# bridge, or use WorkOS as the managed broker. Register:
#   <BETTER_AUTH_URL>/api/auth/oauth2/callback/enterprise-sso
# as the redirect URI in the broker.
# AF_STACK_SSO_LABEL=Enterprise SSO
# AF_STACK_SSO_ISSUER=https://auth.example.com/application/o/af-stack/
# AF_STACK_SSO_DISCOVERY_URL=
# AF_STACK_SSO_CLIENT_ID=
# AF_STACK_SSO_CLIENT_SECRET=
# AF_STACK_SSO_SCOPES=openid email profile

# Billing (stripe | lago | none). Default is stripe.
# AF_STACK_BILLING_ADAPTER=stripe
# STRIPE_SECRET_KEY=
# STRIPE_WEBHOOK_SECRET=
# LAGO_API_URL=http://lago-api:3000
# LAGO_API_KEY=

# Sandboxes — adapter selection (docker | gvisor | firecracker | e2b)
# Defaults to docker. See docs/sandbox-adapters.md for trade-offs.
# AF_STACK_SANDBOX_ADAPTER=docker
# E2B_API_KEY=
# AF_STACK_E2B_BASE_URL=https://api.e2b.app

# Shipwright coding-agent factory. BackAI stores task metadata; AgentField
# owns the execution graph, harness calls, logs, spans, traces, and memory.
# AF_STACK_SHIPWRIGHT_AGENT_CALL=shipwright.build

# Git workload / GitHub PR path (only if using Shipwright production PR flow)
# GH_TOKEN=

# ---------- OAuth-on-behalf-of-user ----------
# Lets agents act on behalf of customers in third-party APIs. These are
# DISTINCT from the better-auth GOOGLE_CLIENT_ID etc. used for operator
# sign-in. better-auth's vars handle LOGIN; the ones below handle the
# AGENT acting AS the user in a 3rd party API (different scopes,
# different tokens, different storage). An OAuth adapter is "configured"
# iff both CLIENT_ID and CLIENT_SECRET are set. Shipped providers:
# Google and GitHub.
#
# OAUTH_GOOGLE_CLIENT_ID=
# OAUTH_GOOGLE_CLIENT_SECRET=
# OAUTH_GITHUB_CLIENT_ID=
# OAUTH_GITHUB_CLIENT_SECRET=
#
# Public URL the runtime advertises to providers as the redirect_uri.
# Must match the URL registered with each provider's OAuth app. Falls
# back to the request's Host header when unset (only useful in dev).
# AF_STACK_PUBLIC_URL=http://localhost:8080
#
# Comma-separated allow-list for OAuth `return_to` URLs (open-redirect
# protection). Localhost dev origins always pass; production deployments
# MUST set this to their customer-app origin(s).
# AF_STACK_OAUTH_ALLOWED_RETURN_ORIGINS=https://app.example.com

# ---------- Native tool adapters (#16 — internal/tools) ----------
#
# Each of the six built-in tool types has an active adapter, chosen
# via env. Single-impl types (fs, exec, http, sql) need no chooser.

# Browser: "browser-use" (default) | "steel" | "browserbase" | "playwright"
# browser-use = self-hosted sidecar; reference impl ships behind the
# `browser` compose profile: docker compose --profile browser up -d
# steel / browserbase = hosted providers (API key); playwright = any
# CDP websocket endpoint (e.g. Browserless: wss://chrome.browserless.io?token=KEY).
# All credentials can also be entered in the dashboard under
# Platform -> Integrations (env wins; UI values apply on restart).
# ALLOW_PRIVATE re-permits loopback/RFC-1918 endpoints (required for a
# compose-network sidecar; the SSRF guard blocks them by default).
# AF_STACK_TOOL_BROWSER=browser-use
# BROWSER_USE_URL=http://browser-sidecar:8000
# AF_STACK_BROWSER_ALLOW_PRIVATE=true
# STEEL_API_KEY=
# STEEL_BASE_URL=https://api.steel.dev
# BROWSERBASE_API_KEY=
# BROWSERBASE_PROJECT_ID=
# PLAYWRIGHT_ENDPOINT=

# Search: "searxng" (default) | "tavily" | "brave" | "exa" | "duckduckgo"
# AF_STACK_TOOL_SEARCH=searxng
# SEARXNG_URL=http://searxng:8888
# TAVILY_API_KEY=
# BRAVE_API_KEY=
# EXA_API_KEY=

# ---------- Observability ----------

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_SERVICE_NAME=af-stack
LOG_LEVEL=info
LOG_FORMAT=json

# ---------- Development ----------

NODE_ENV=development
# Advanced coding-agent surfaces are available but hidden from first-run
# navigation unless explicitly enabled.
AF_STACK_SHOW_SHIPWRIGHT=false
POSTGRES_PORT=5432
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
LITELLM_PORT=4000
AGENTFIELD_PORT=8081
AF_STACK_PORT=8080
AF_STACK_METRICS_PORT=9090
AF_STACK_DASHBOARD_PORT=33000
AF_STACK_CUSTOMER_APP_PORT=34000