example.env

# ===========================================
# Logging Configuration
# ===========================================
# Log level for the application (default: INFO)
# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
# XAGENT_LOG_LEVEL="INFO"

# ===========================================
# Docker Compose Configuration
# ===========================================
# When using docker-compose.yml, DATABASE_URL is automatically set.
# You only need to configure the PostgreSQL password below.
# POSTGRES_PASSWORD is used by both postgres and xagent services.
POSTGRES_PASSWORD="xagent_password"

# Web service port (default: 80)
# Frontend and backend are both accessible through this single port
# nginx will route /api/* to backend and others to frontend
PORT="80"

# ===========================================
# Database Configuration (optional)
# ===========================================
# For local development without Docker Compose, uncomment and configure:
# DATABASE_URL="postgresql://xagent:xagent_password@localhost:5432/xagent"
# Or use SQLite (default, no configuration needed):
# DATABASE_URL="sqlite:///home/xagent/.xagent/xagent.db"

# ===========================================
# Hot Path Cache Configuration
# ===========================================
# Enables short-TTL cache for high-frequency task/agent/model read paths.
# Docker Compose deployments start a Redis service and set
# XAGENT_REDIS_URL=redis://redis:6379/0 automatically.
#
# For local backend runs outside Docker Compose, uncomment these if Redis is
# running on your machine, for example via `brew services start redis`.
# XAGENT_REDIS_URL="redis://localhost:6379/0"
# XAGENT_HOT_PATH_CACHE_ENABLED="true"
# Default TTL for agent/model response cache entries.
# XAGENT_HOT_PATH_CACHE_TTL_SECONDS="30"
# Default TTL for task polling cache entries.
# XAGENT_HOT_PATH_TASK_CACHE_TTL_SECONDS="30"

# ===========================================
# Background Jobs / Triggers Configuration
# ===========================================
# Enables Celery-backed durable background jobs for trigger processing and
# knowledge-base ingestion. Agent execution is intentionally not routed through
# Celery.
#
# Docker Compose starts worker/scheduler services and sets these automatically.
# Redis DB 0 is reserved for hot-path cache. Redis DB 1 is the Celery broker.
# XAGENT_CELERY_ENABLED="true"
# XAGENT_CELERY_BROKER_URL="redis://localhost:6379/1"
# Background job status/result is stored in the database, so a Celery result
# backend is normally unnecessary. If enabled, keep it separate from DB 0/1.
# XAGENT_CELERY_RESULT_BACKEND="redis://localhost:6379/2"
# Broker visibility timeout for long-running KB jobs.
# XAGENT_BACKGROUND_JOB_VISIBILITY_TIMEOUT_SECONDS="3600"
# Default max attempts for newly-created durable jobs.
# XAGENT_BACKGROUND_JOB_MAX_RETRIES="3"
# Stale non-terminal jobs are requeued by the scheduler after this age.
# XAGENT_BACKGROUND_JOB_STALE_SECONDS="7200"
# Scheduler interval for scanning stale background jobs.
# XAGENT_BACKGROUND_JOB_SWEEP_INTERVAL_SECONDS="300"

# ===========================================
# LLM API Keys
# ===========================================
# OPENAI_API_KEY="your-openai-api-key"
INFERENCE_API_KEY="your-inference-api-key"
# DEEPSEEK_API_KEY="your-deepseek-api-key"
# Optional DeepSeek defaults
# DEEPSEEK_MODEL_NAME="deepseek-v4-flash"
# Official default base URL does not use the legacy /v1 suffix
# DEEPSEEK_BASE_URL="https://api.deepseek.com"
# DEEPSEEK_REASONING_EFFORT="high"

# ===========================================
# Embedding API Keys (for vector memory)
# ===========================================
DASHSCOPE_API_KEY="your-dashscope-api-key"
OPENAI_EMBEDDING_API_KEY="your-openai-api-key"

# Memory Store Configuration
# Optional: Override automatic detection
# MEMORY_STORE_TYPE=in_memory|lancedb
# MEMORY_LANCEDB_DIR=./memory_store
#
# Auto-run LanceDB user_id migration on startup (default: false)
# Set to true to run background backfill when startup detects missing user_id fields.
# LANCEDB_AUTO_MIGRATE=true

# Milvus Vector Store Provider (optional, provider layer only)
# Used by xagent.providers.vector_store.milvus.get_client_from_env()
# Install dependency first: pip install pymilvus
# MILVUS_URI="http://localhost:19530"
# MILVUS_TOKEN=""
# MILVUS_DB_NAME=""

# ===========================================
# Other Configuration
# ===========================================
# JWT Authentication (required for production)
# Generate a secure secret with:
# python -c "import secrets; print(secrets.token_urlsafe(48))"
XAGENT_JWT_SECRET="replace-with-a-long-random-secret"
XAGENT_JWT_ALGORITHM="HS256"
# Access token expiry in minutes (default: 120)
XAGENT_ACCESS_TOKEN_EXPIRE_MINUTES="120"
# Refresh token expiry in days (default: 7)
XAGENT_REFRESH_TOKEN_EXPIRE_DAYS="7"
# Minimum password length for setup/register/change-password (default: 6)
XAGENT_PASSWORD_MIN_LENGTH="6"

# Image processing
CONCURRENT=5

# Langfuse Tracing
LANGFUSE_TRACING_ENABLED="true"
# Langfuse Python SDK v4 uses `base_url`; keep `LANGFUSE_HOST` only for legacy env fallback.
LANGFUSE_BASE_URL="http://127.0.0.1:3000"
LANGFUSE_PUBLIC_KEY="public key"
LANGFUSE_SECRET_KEY="secret key"

# Per-field byte cap for the LLM I/O audit trace written to trace_events
# (data.messages / data.response / etc.). Anything larger is truncated with a
# "[truncated N chars]" suffix. A long DAG task hitting all audit sites can
# otherwise write multi-MB rows. Default: 50000 (~50KB).
# XAGENT_MAX_TRACE_PAYLOAD_BYTES="50000"

# Web Search API Keys
# Provider selection: auto, google, tavily, exa, zhipu (default: auto)
# In auto mode, priority is Zhipu > Tavily > Exa > Google.
XAGENT_WEB_SEARCH_PROVIDER="auto"

# Website import TLS fingerprint impersonation for WAF-protected sites.
# Leave empty/none for plain httpx. Use auto to try the crawler fallback chain.
# Requires installing the optional extra: pip install "xagent[waf-crawl]"
# XAGENT_WEB_CRAWL_TLS_IMPERSONATE="auto"

# Zhipu Web Search (recommended for Chinese users, get key at https://open.bigmodel.cn/)
ZHIPU_API_KEY=""

# Tavily Search API (alternative, get key at https://tavily.com)
TAVILY_API_KEY=""

# Exa AI-powered Search (get key at https://exa.ai)
EXA_API_KEY=""

# Google Custom Search (fallback, requires Google Cloud setup)
GOOGLE_API_KEY=""
GOOGLE_CSE_ID=""

# ===========================================
# Google OAuth Configuration (Optional)
# ===========================================
# Required for Google Login and Google Drive integration
# Create credentials at https://console.cloud.google.com/apis/credentials
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
# Redirect URI for Google OAuth callback (Required for Google Login)
# Example: http://localhost:8000/api/auth/google/callback
GOOGLE_REDIRECT_URI=""

# ===========================================
# LinkedIn OAuth Configuration (Optional)
# ===========================================
# Required for LinkedIn integration in MCP
# Create credentials at https://www.linkedin.com/developers/apps/new
LINKEDIN_CLIENT_ID=""
LINKEDIN_CLIENT_SECRET=""
# Redirect URI for LinkedIn OAuth callback
# Example: http://localhost:8000/api/auth/linkedin/callback
LINKEDIN_REDIRECT_URI=""

# Note:
# - If embedding API keys are configured, LanceDB will be used automatically
# - LanceDB storage path: <project_root>/memory_store/
# - Without embedding keys, InMemory storage will be used
# - Milvus support is currently optional at provider layer and does not change defaults

# ===========================================
# Skills Directories Configuration
# ===========================================
# Comma-separated list of skill directory paths
# Supports:
# - Absolute paths: /path/to/skills1,/path/to/skills2
# - Relative paths: ./skills,../shared_skills
# - Home directory: ~/skills,~/custom/skills
# - Environment variables: $HOME/skills,${USERPROFILE}/skills
#
# Examples:
XAGENT_EXTERNAL_SKILLS_LIBRARY_DIRS=""
# XAGENT_EXTERNAL_SKILLS_LIBRARY_DIRS="/path/to/custom/skills"
# XAGENT_EXTERNAL_SKILLS_LIBRARY_DIRS="~/skills,/usr/local/skills,$HOME/custom_skills"
# XAGENT_EXTERNAL_SKILLS_LIBRARY_DIRS="./local_skills,../shared_skills"

# ===========================================
# Storage and Directory Configuration
# ===========================================
# Root directory for all xagent data (default: ~/.xagent)
# XAGENT_STORAGE_ROOT=""

# Uploads directory for user files (default: src/xagent/web/uploads)
# For containerized deployments, use a persistent volume path
# XAGENT_UPLOADS_DIR=""

# Maximum per-file upload size enforced by the backend.
# Nginx maintains a separate, larger defense-in-depth ceiling (see docker/nginx.conf).
# Supports raw bytes or human-readable values like 100M, 1G, 512K.
XAGENT_MAX_UPLOAD_SIZE="100M"

# Durable file storage for user-visible uploads and registered workspace outputs.
# Defaults to file://$XAGENT_STORAGE_ROOT/files for local development.
# For S3-compatible storage, use a URI with bucket and optional prefix.
# XAGENT_FILE_STORAGE_URI="file:///home/xagent/.xagent/files"
# XAGENT_FILE_STORAGE_URI="s3://xagent-bucket/prod/files"

# Optional fsspec provider options as JSON. For S3-compatible providers this can
# include endpoint_url, region_name, profile, key, secret, or config_kwargs.
# S3 storage defaults to bounded botocore timeouts/retries so unavailable
# storage fails quickly; override config_kwargs here if your deployment needs
# longer waits.
# XAGENT_FILE_STORAGE_OPTIONS='{"endpoint_url":"https://s3.example.com","region_name":"us-east-1"}'

# Local temp/cache directory for materializing durable files when libraries need paths.
# XAGENT_FILE_MATERIALIZE_DIR="/tmp/xagent-materialized"

# Sync DB-registered local files to S3 durable storage during backend startup.
# Only applies when XAGENT_FILE_STORAGE_URI uses s3://. Missing local files are
# logged and skipped; unexpected S3 errors fail startup.
# XAGENT_FILE_STORAGE_STARTUP_SYNC_ENABLED="true"

# Redirect authenticated preview/download requests to short-lived durable-object
# URLs when the storage backend can sign them. Keep disabled unless the signed
# URL endpoint is reachable by browsers (for example public S3/MinIO or CDN).
# XAGENT_FILE_DELIVERY_REDIRECT_ENABLED="false"
# XAGENT_FILE_DELIVERY_SIGNED_URL_TTL_SECONDS="300"

# Let nginx serve local upload bytes after the backend authorizes a file_id.
# This requires docker/nginx.conf's internal location and a shared read-only
# uploads volume mounted into nginx. Keep disabled for direct local backend runs.
# XAGENT_FILE_DELIVERY_ACCEL_REDIRECT_ENABLED="false"
# XAGENT_FILE_DELIVERY_ACCEL_REDIRECT_PREFIX="/_xagent_internal_files/"

# External upload directories for knowledge base file access
# Comma-separated list of directory paths (existing dirs only)
# XAGENT_EXTERNAL_UPLOAD_DIRS="/path/to/uploads1,/path/to/uploads2"

# Web module directory (default: src/xagent/web)
# XAGENT_WEB_DIR=""

# LanceDB database path (default: data/lancedb, relative to cwd)
# For production, use an absolute path under XAGENT_STORAGE_ROOT
# LANCEDB_PATH=""

# Database encryption key
# Generate one with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ENCRYPTION_KEY="RQMpe38gK3m0szjpSmTNw_sP3Y54r6hDc6JewBoPKXc="

# ===========================================
# Tool Output Configuration
# ===========================================
# Maximum length per string in tool output (default: 51200, ~50KB)
# This limits individual string values, not total output size
# XAGENT_TOOL_MAX_OUTPUT_LENGTH="51200"

# Maximum number of fields/items in dict/list (default: 1000)
# This limits collection cardinality to prevent excessive output
# XAGENT_TOOL_MAX_FIELD_COUNT="1000"

# Maximum recursion depth for nested structures (default: 20)
# This prevents excessively deep nesting in tool output
# XAGENT_TOOL_MAX_RECURSION_DEPTH="20"

# ===========================================
# External Database Connections (for SQL Query Tool)
# ===========================================
# SQL tool supports PostgreSQL, MySQL, and SQLite
# Connection format: XAGENT_EXTERNAL_DB_<NAME>=<connection_url>
#
# Install required database drivers:
# - PostgreSQL: pip install psycopg2-binary (or psycopg2)
# - MySQL: pip install pymysql (or mysqlclient)
# - SQLite: built-in (no installation needed)
#
# Format of the url is the same as used by SQLAlchemy, async drivers are not supported currently.
# Examples:
# XAGENT_EXTERNAL_DB_ANALYTICS="postgresql://user:password@localhost:5432/analytics"
# XAGENT_EXTERNAL_DB_PROD="mysql+pymysql://user:password@localhost:3306/production"
# XAGENT_EXTERNAL_DB_LOCAL="sqlite:///path/to/database.db"

# ===========================================
# Sandbox Configuration
# ===========================================
# Enable/disable sandbox execution environment (default: false)
# SANDBOX_ENABLED="false"

# Sandbox implementation type (default: docker)
# Available options: docker, boxlite
# SANDBOX_IMPLEMENTATION="docker"

# Recommended Docker deployment topology:
# - Prefer a dedicated Docker engine for sandbox workloads, for example a separate VM,
#   a dedicated Docker host, or a dedicated DinD/containerized Docker daemon used only by Xagent.
# - Avoid sharing the host's primary Docker daemon with sandbox execution if possible.
#
# Security warning:
# - Do NOT mount the host Docker socket (for example /var/run/docker.sock) directly into the
#   Xagent backend when it may execute untrusted sandbox code.
# - Access to that socket is effectively root-equivalent on the Docker host: an attacker could
#   start privileged containers, mount host filesystems, read secrets, or escape the sandbox
#   and gain control of the host.
#
# Suggested hardening measure:
# - Put a restricted proxy such as Tecnativa/docker-socket-proxy in front of the Docker
#   daemon.
#
# When using SANDBOX_IMPLEMENTATION="docker", set DOCKER_HOST if your Docker-compatible
# runtime endpoint is not the default (for example Podman socket/service)
# DOCKER_HOST=""

# Docker sibling deployments resolve sandbox code mounts on the Docker host,
# not inside the Xagent backend container. Set this to the host-side project
# checkout root when it differs from the backend container path.
# XAGENT_SANDBOX_HOST_PROJECT_ROOT=""

# Docker sibling deployments also resolve workspace/storage mounts on the Docker
# host. Set this to the host-side Xagent storage root when manual deployments
# bind a different host path into the backend as XAGENT_STORAGE_ROOT.
# The provided Compose overlay accepts XAGENT_HOST_STORAGE_ROOT and passes it
# through as XAGENT_SANDBOX_HOST_STORAGE_ROOT automatically.
# XAGENT_SANDBOX_HOST_STORAGE_ROOT=""

# Boxlite home directory (default: ~/.boxlite)
# Takes effect only when using the boxlite implementation
# BOXLITE_HOME_DIR=""

# Sandbox container image (default: xprobe/xagent-sandbox:latest)
# We should pin the version at release (`latest` may lead to caching problems)
# SANDBOX_IMAGE=""

# Sandbox CPU core limit (default: 1)
# SANDBOX_CPUS=""

# Sandbox memory limit in MB (default: 512)
# SANDBOX_MEMORY=""

# ===========================================
# Sandbox Volume Mount Configuration
# ===========================================
# Mount host directories into sandbox (Docker-style format)
# Format: SANDBOX_VOLUMES="src:dst:mode;src:dst:mode"
#   - src: Path on host machine (supports ~ expansion)
#   - dst: Path inside sandbox container
#   - mode: 'ro' (read-only) or 'rw' (read-write), default is 'ro' when omitted
#   - Multiple volumes are separated by semicolon (;)
#   - In Docker sibling mode, src is interpreted by the Docker host daemon.
#     Use absolute host paths; relative paths and ~ are rejected.
#
# Examples:
# Mount Python venv site-packages (read-only recommended)
# SANDBOX_VOLUMES="/home/user/my-python-site:/usr/local/lib/python3.14/site-packages:ro"
#
# Mount node_modules
# SANDBOX_VOLUMES="/home/user/my-node_modules:/usr/local/lib/node_modules"
#
# Mount multiple directories
# SANDBOX_VOLUMES="/home/user/my-python-site:/usr/local/lib/python3.14/site-packages;/home/user/my-python-app:/opt/my-python-app"

# ===========================================
# Sandbox Environment Variables
# ===========================================
# Additional environment variables to inject into sandbox
# Format: SANDBOX_ENV="KEY1=value1;KEY2=value2"
#   - Multiple variables are separated by semicolon (;)
#   - Values should not contain semicolon
#
# Example: Set PYTHONPATH to include mounted site-packages
# SANDBOX_ENV="PYTHONPATH=/home/user/my-python-app:/opt/my-python-app"