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"

# ===========================================
# LLM API Keys
# ===========================================
OPENAI_API_KEY="your-openai-api-key"
INFERENCE_API_KEY="your-inference-api-key"
DEEPSEEK_API_KEY="your-deepseek-api-key"

# ===========================================
# 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_HOST="http://127.0.0.1:3000"
LANGFUSE_PUBLIC_KEY="public key"
LANGFUSE_SECRET_KEY="secret key"

# Web Search API Keys (priority: Zhipu > Tavily > Exa > Google)
# 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"

# 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=""

# 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 (;)
#
# 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"