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"

# PostgreSQL image tag for the bundled postgres service (default: 17-bookworm).
# A postgres_data volume initialized by v16 must pin "16-bookworm" until it is
# migrated. See the upgrade runbook in docker/README.md.
# POSTGRES_IMAGE_TAG="16-bookworm"

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

# SQLAlchemy connection pool settings (non-SQLite databases only). These
# apply to EACH of the two engines a process may create — the shared web
# engine and the ad-hoc engine behind create_db_session() (workspace file
# registration etc.) — so the worst case per process is
# 2 x (pool size + max overflow). Size that, multiplied by backend/worker
# process count, below PostgreSQL's max_connections.
# XAGENT_DB_POOL_SIZE="10"
# XAGENT_DB_MAX_OVERFLOW="20"
# Seconds to wait for a free pooled connection before raising.
# XAGENT_DB_POOL_TIMEOUT_SECONDS="30"

# Task execution leases keep one runner from executing the same task/run twice.
# The heartbeat defaults to one third of the TTL. Expired leases are recovered
# automatically by every backend process; final conditional updates ensure only
# one process wins each recovery.
# XAGENT_TASK_LEASE_TTL_SECONDS="60"
# XAGENT_TASK_LEASE_HEARTBEAT_SECONDS="20"
# XAGENT_TASK_LEASE_RECOVERY_INTERVAL_SECONDS="20"
# XAGENT_TASK_LEASE_RECOVERY_BATCH_SIZE="100"

# Stale upload-compensation claims are reconciled by every backend process.
# The grace period prevents a live request from being recovered prematurely;
# exact conditional updates ensure only one process settles each claim. Each
# process examines at most one configured batch per polling tick.
# XAGENT_UPLOADED_FILE_RECOVERY_INTERVAL_SECONDS="60"
# XAGENT_UPLOADED_FILE_RECOVERY_STALE_SECONDS="300"
# XAGENT_UPLOADED_FILE_RECOVERY_BATCH_SIZE="100"

# How long shutdown waits (seconds) for the background orphaned temp-file sweep
# to stop after its cooperative stop flag is set. Bounds only the wait, not the
# uncancellable walk itself; raise it on very large uploads trees.
# XAGENT_TEMP_FILE_CLEANUP_SHUTDOWN_TIMEOUT_SECONDS="10"

# Per-server timeout (seconds) for MCP tool initialization during agent
# setup (connect + initialize + list-tools, including retries and cleanup).
# A server that exceeds it is skipped for that task. 0 disables the timeout.
# XAGENT_MCP_TOOL_INIT_TIMEOUT_SECONDS="60"

# ===========================================
# 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"
# Longest a non-terminal job may go without a durable row update (progress
# or status persistence) before the scheduler requeues it. Not a runtime
# limit: a job that keeps persisting progress is never requeued for age.
# XAGENT_BACKGROUND_JOB_STALE_SECONDS="7200"
# Scheduler interval for scanning stale background jobs.
# XAGENT_BACKGROUND_JOB_SWEEP_INTERVAL_SECONDS="300"
# Public share-channel upload orphan GC (#973). A task-less public-share upload
# is bound to its task at run start; if the guest never finishes task creation
# it stays orphaned. An in-app background loop (runs in every deployment, no
# Celery required) reaps rows older than the TTL that still carry the
# task-less-share marker and have no task_id.
# Per-tick load: up to 20 keyset pages x 500 rows (10,000 rows, each with a
# durable-object + local-file delete), one short DB session per page. While a
# backlog remains the loop continues after a ~1s breather instead of sleeping,
# so drain throughput does not depend on the interval below; the interval only
# sets how often an already-drained backlog is re-checked.
# XAGENT_TASKLESS_UPLOAD_TTL_SECONDS="172800"        # 48h; GC-eligible age
# XAGENT_ORPHAN_UPLOAD_SWEEP_INTERVAL_SECONDS="3600" # idle re-check interval
# Workforce builder preview runs ("test before save", workforce_id NULL) are
# only invalidated client-side; an abandoned tab/browser crash/network drop
# leaves one active server-side forever. The scheduled sweep (piggybacks on
# the existing trigger-scan Celery Beat tick) cancels runs non-terminal past
# this age.
# XAGENT_WORKFORCE_PREVIEW_RUN_STALE_SECONDS="7200" # 2h; GC-eligible age
# Backend dispatcher for prepared trigger runs. Celery scans scheduled triggers,
# but agent execution is started by backend processes.
# XAGENT_TRIGGER_DISPATCHER_ENABLED="true"
# XAGENT_TRIGGER_DISPATCHER_INTERVAL_SECONDS="5"
# XAGENT_TRIGGER_DISPATCHER_BATCH_SIZE="20"
# Rate limits for the public trigger callback endpoint (keyed by callback id +
# caller IP) and trigger create/update/delete APIs (keyed by user). Uses Redis
# when XAGENT_REDIS_URL is set; otherwise limits are per backend process.
# XAGENT_TRIGGER_CALLBACK_RATE_LIMIT="120/minute"
# Per-IP ceiling across all callback ids (blocks rotating-id floods).
# XAGENT_TRIGGER_CALLBACK_IP_RATE_LIMIT="600/minute"
# XAGENT_TRIGGER_CRUD_RATE_LIMIT="60/minute"
# Public share-channel abuse controls (#973). Same Redis-backed limiter; all
# are rate strings in the limits notation. Auth is keyed per share token +
# per caller IP; task-create per guest + per share token; ws turns and uploads
# per guest; ws connection attempts (pre-auth, so no guest exists yet) per
# caller IP. The run quotas cap owner-billed runs a link/guest can start per
# rolling window so one public link cannot drain the owner's team quota.
# XAGENT_SHARE_AUTH_RATE_LIMIT="60/minute"
# XAGENT_SHARE_AUTH_IP_RATE_LIMIT="300/minute"
# XAGENT_SHARE_TASK_CREATE_RATE_LIMIT="30/minute"
# XAGENT_SHARE_TASK_CREATE_TOKEN_RATE_LIMIT="120/minute"
# XAGENT_SHARE_WS_TURN_RATE_LIMIT="60/minute"
# XAGENT_SHARE_WS_CONNECT_IP_RATE_LIMIT="120/minute"
# XAGENT_SHARE_UPLOAD_RATE_LIMIT="60/minute"
# Widget uploads are keyed per widget entity + per caller IP instead of per
# guest: the widget guest_id is client-supplied (rotatable), unlike the
# server-minted share guest_id.
# XAGENT_WIDGET_UPLOAD_RATE_LIMIT="240/minute"
# XAGENT_WIDGET_UPLOAD_IP_RATE_LIMIT="60/minute"
# Widget websocket abuse controls (#1056): connection attempts per caller IP
# (pre-auth, refused pre-accept when over budget) and run-starting turns per
# caller IP (tight) + per widget entity (loose backstop). Separate buckets
# from the share websocket limits so the two public channels cannot consume
# each other's budgets.
# XAGENT_WIDGET_WS_CONNECT_IP_RATE_LIMIT="120/minute"
# XAGENT_WIDGET_WS_TURN_IP_RATE_LIMIT="60/minute"
# XAGENT_WIDGET_WS_TURN_RATE_LIMIT="240/minute"
# Widget HTTP/quota abuse controls (#1108): the remaining share-path controls
# with no widget counterpart. Every widget gate uses the tight-per-IP /
# loose-per-entity pairing: the caller IP is the per-visitor/per-abuser bound
# (the widget guest_id is client-supplied, so it is never a limiter key), and
# the per-entity bucket is a loose aggregate backstop across one embedded
# agent/workforce's visitors. Auth + embed-ticket minting share the same
# limit *configuration* and the same per-IP counter, but their per-entity
# counters are disjoint (embed-ticket keys the entity bucket on the widget
# key; auth keys it on the owner entity from the ticket's signed claims), so
# the two env values below are shared budgets only in the per-IP dimension.
# The auth entity default is deliberately loose (1200/min, a 4:1 entity:IP
# ratio matching the sibling widget gates) because both endpoints fire on
# every page load and the entity is shared by all a widget's visitors — a
# tight per-entity bucket would 429 ordinary visitors on a busy embed, and
# an auth denial is fail-closed client-side (the widget never loads). The
# widget run quota caps owner-billed runs per rolling window with a
# per-creating-IP sub-quota (keyed per widget, so exhausting it on one embed
# never blocks the same network on another); NOTE it applies to already-live
# widget tasks as soon as it deploys, and it is charged per conversation turn,
# not once per task. Separate buckets from the share limits.
# NAT / shared egress: every per-IP bucket below is shared by all genuine
# visitors behind one address — a corporate NAT or a carrier CGNAT can put
# thousands of people on one IP — so raise the per-IP values for deployments
# fronted by large shared egress. CAUTION: every per-IP bucket also needs
# XAGENT_TRUSTED_PROXY_HOPS set correctly behind a reverse proxy — with 0
# hops, all traffic resolves to the proxy's own IP and a per-IP cap silently
# becomes one global cap for the deployment; set it too high and the client
# controls the derived IP through X-Forwarded-For.
# XAGENT_WIDGET_AUTH_RATE_LIMIT="1200/minute"
# XAGENT_WIDGET_AUTH_IP_RATE_LIMIT="300/minute"
# XAGENT_WIDGET_TASK_CREATE_RATE_LIMIT="240/minute"
# XAGENT_WIDGET_TASK_CREATE_IP_RATE_LIMIT="60/minute"
# XAGENT_WIDGET_RUN_QUOTA="500/day"
# XAGENT_WIDGET_RUN_IP_QUOTA="120/hour"
# XAGENT_SHARE_RUN_QUOTA="500/day"
# XAGENT_SHARE_RUN_GUEST_QUOTA="60/hour"
# Behind a reverse proxy, set the number of trusted proxy hops so the caller
# IP for rate limiting is read from X-Forwarded-For. 0 = use the peer address.
# IMPORTANT: when the backend sits behind a reverse proxy / load balancer and
# this stays at 0, every request appears to come from the proxy's IP, so every
# per-IP limit (share/widget auth, task-create, the widget run IP sub-quota,
# trigger callbacks) silently collapses into a single global cap across ALL
# callers and can hard-429 legitimate traffic. Set it to the number of proxies
# you control in front of the backend (e.g. 1 for a single nginx/ingress hop —
# the bundled docker-compose.yml already sets 1 for its nginx). Do NOT set it
# HIGHER than the real count: X-Forwarded-For is append-order, so an over-count
# reads a client-supplied entry and lets the caller spoof the derived IP —
# which now also picks a persisted quota key (widget_client_ip). Match it to
# your real topology exactly.
# XAGENT_TRUSTED_PROXY_HOPS="0"
# Gmail incoming-email triggers (per-mailbox Pub/Sub provisioning).
#
# Credentials: the backend uses Application Default Credentials (ADC). Either
# run on GCP with an attached service account, or set
# GOOGLE_APPLICATION_CREDENTIALS to a service-account JSON key file. The
# service account needs roles/pubsub.editor (create/delete topics and
# subscriptions) on the project below, and each per-mailbox topic must allow
# gmail-api-push@system.gserviceaccount.com to publish
# (roles/pubsub.publisher) - granted automatically during provisioning.
#
# Master switch for the Gmail watch feature: gates watch registration (on
# OAuth connect and on Gmail trigger create/update/enable) as well as the
# background renewal and retry scans. While "false" (the default), Gmail
# triggers report a failed provisioning status with an explicit disabled
# error and no new watches are registered. Disabling this flag does not stop
# an existing Gmail watch: callbacks can remain deliverable until that watch
# expires or its mailbox resources are explicitly torn down.
# Teardown-on-unbind is deliberately ungated: rebinding, disabling, or
# deleting a Gmail trigger still releases the old mailbox's watch/Pub/Sub
# resources while this flag is off.
# The operator endpoint-reconciliation CLI (reconcile_gmail_push_endpoints)
# is also deliberately ungated, so endpoints can be migrated before enabling
# this flag.
# XAGENT_GMAIL_WATCH_ENABLED="false"
# XAGENT_GMAIL_PUBSUB_PROJECT_ID="your-gcp-project"
# Deterministic per-mailbox resource names: {prefix}-{mailbox-hash}.
# XAGENT_GMAIL_PUBSUB_TOPIC_PREFIX="xagent-gmail"
# XAGENT_GMAIL_PUBSUB_SUBSCRIPTION_PREFIX="xagent-gmail-push"
# Pub/Sub client transport: "grpc" (default) or "rest". Use "rest" behind
# egress proxies that cannot tunnel gRPC (the gRPC channel hangs there and
# Gmail provisioning stays pending without an error).
# XAGENT_GMAIL_PUBSUB_TRANSPORT="grpc"
# Canonical public base URL of this backend API. Browser-facing and MCP OAuth
# flows use this base. This is NOT the frontend URL (XAGENT_APP_BASE_URL).
# When unset, MCP OAuth
# redirect URIs fall back to XAGENT_APP_BASE_URL — that only works when the
# frontend origin proxies /api/* to this backend (e.g. the nginx compose
# setup), so split-port local development must set this explicitly.
# XAGENT_PUBLIC_API_BASE_URL="https://api.example.com"
# Optional backend URL advertised to server-to-server Gmail Pub/Sub and A2A
# clients. Regional deployments can set their direct origin here; when unset,
# it falls back to XAGENT_PUBLIC_API_BASE_URL for backward compatibility.
# XAGENT_S2S_API_BASE_URL="https://region-origin.example.com"
# Deprecated Gmail-only fallback retained for existing deployments. Prefer
# XAGENT_S2S_API_BASE_URL for new regional configurations.
# XAGENT_TRIGGER_CALLBACK_BASE_URL="https://legacy-callback.example.com"
# Service-account email whose OIDC identity signs push deliveries.
# XAGENT_GMAIL_PUBSUB_PUSH_SERVICE_ACCOUNT="pubsub-push@your-gcp-project.iam.gserviceaccount.com"
# Trigger create/update returns a pending registration after this many seconds
# while provisioning converges in the background.
# XAGENT_GMAIL_REGISTRATION_TIMEOUT_SECONDS="10"
# XAGENT_GMAIL_WATCH_RENEWAL_INTERVAL_SECONDS="3600"
# XAGENT_GMAIL_WATCH_RENEWAL_LEAD_SECONDS="86400"

# ===========================================
# 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"
# ElevenLabs speech (ASR/TTS)
# ELEVENLABS_API_KEY="your-elevenlabs-api-key"
# ELEVENLABS_BASE_URL="https://api.elevenlabs.io"
# OpenRouter official-provider pinning is disabled by default to preserve
# OpenRouter fallback behavior. Set to true to route official model families
# (OpenAI, Anthropic, Google, DeepSeek, MiniMax, Z.AI) only to official endpoints.
# XAGENT_OPENROUTER_OFFICIAL_PROVIDERS_ONLY="false"

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

# ===========================================
# DeepDoc Remote Inference (Xinference)
# ===========================================
# Offload DeepDoc PDF parsing (OCR/layout/table models) to a remote Xinference
# server with a GPU, using the DeepDoc model's task="parse" whole-document
# pipeline. When set, PDFs are parsed remotely; every other format, and every
# PDF when this is unset, is parsed locally. On remote failure xagent logs a
# warning and falls back to local parsing automatically.
# XAGENT_DEEPDOC_XINFERENCE_URL="http://gpu-host:9997"

# UID of the launched DeepDoc model to target (default: DeepDoc).
# XAGENT_DEEPDOC_XINFERENCE_MODEL_UID="DeepDoc"

# API key, sent as the bearer token; falls back to XINFERENCE_API_KEY if unset.
# XAGENT_DEEPDOC_XINFERENCE_API_KEY=""

# Alternative to the API key: credentials exchanged for a JWT at POST /token.
# When both are set, these win. Leave all of them unset for a cluster that runs
# without authentication.
# XAGENT_DEEPDOC_XINFERENCE_USERNAME=""
# XAGENT_DEEPDOC_XINFERENCE_PASSWORD=""

# Request timeout in seconds for one whole-document parse (default: 1800).
# XAGENT_DEEPDOC_XINFERENCE_TIMEOUT_SECONDS="1800"

# ===========================================
# 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"
# Password reset link expiry in minutes (default: 30)
# XAGENT_PASSWORD_RESET_EXPIRE_MINUTES="30"
# Frontend base URL used in reset-password emails
# XAGENT_APP_BASE_URL="http://localhost:3000"

# Slack workspace OAuth (optional).
# Create one distributed Slack app, enable Socket Mode and configure the bot
# scopes/events shown on the Channels page. The Redirect URL registered in
# Slack must exactly match XAGENT_SLACK_REDIRECT_URI. If the explicit redirect
# is omitted, Xagent derives it as:
#   {XAGENT_PUBLIC_API_BASE_URL}/api/channels/slack/oauth/callback
# Keep Slack token rotation disabled; this integration stores the workspace's
# non-expiring bot token returned by oauth.v2.access.
# Socket Mode uses one shared app-level token (connections:write) and routes
# workspace events by team_id; users never need to paste xoxb/xapp tokens.
# The Slack app must subscribe to these bot events: app_mention,
# message.channels, message.groups, message.im, message.mpim, plus
# app_uninstalled and tokens_revoked so Xagent can deactivate the channel
# when a workspace removes the app.
# Workspace tokens are encrypted at rest with ENCRYPTION_KEY (see the security
# section); the OAuth install flow refuses to start while ENCRYPTION_KEY is
# unset or still the built-in dev default. Generate one with:
#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# XAGENT_SLACK_CLIENT_ID="123456789.123456789"
# XAGENT_SLACK_CLIENT_SECRET="your-slack-client-secret"
# XAGENT_SLACK_APP_TOKEN="xapp-your-app-level-token"
# XAGENT_SLACK_REDIRECT_URI="https://api.example.com/api/channels/slack/oauth/callback"

# ===========================================
# SMTP Configuration (for password reset email)
# ===========================================
# XAGENT_SMTP_HOST="smtp.example.com"
# XAGENT_SMTP_PORT="587"
# XAGENT_SMTP_USERNAME=""
# XAGENT_SMTP_PASSWORD=""
# XAGENT_SMTP_USE_TLS="true"
# XAGENT_SMTP_USE_SSL="false"
# XAGENT_SMTP_FROM_EMAIL="no-reply@example.com"
# XAGENT_SMTP_FROM_NAME="Xagent"

# Google OIDC login (optional)
# Configure these to enable "Continue with Google" on the web login page.
# XAGENT_GOOGLE_OIDC_CLIENT_ID="your-google-oauth-client-id"
# XAGENT_GOOGLE_OIDC_CLIENT_SECRET="your-google-oauth-client-secret"
# XAGENT_GOOGLE_OIDC_REDIRECT_URI="http://localhost:8000/api/auth/oidc/google/callback"
# XAGENT_FRONTEND_URL="http://localhost:3000"
# XAGENT_SESSION_SECRET="change-me-to-a-random-session-secret"
# XAGENT_OIDC_LOGIN_TTL_SECONDS="600"
# XAGENT_OIDC_EXCHANGE_TTL_SECONDS="120"

# MCP OAuth local development only.
# Set XAGENT_PUBLIC_API_BASE_URL above to the externally reachable backend
# origin used for automatic {base}/api/mcp/oauth/callback redirect URIs.
# Keep disabled in production; enabling this allows OAuth discovery/token URLs
# to target localhost, private, link-local, reserved, multicast, or unspecified
# addresses for local authorization-server testing.
# XAGENT_MCP_OAUTH_ALLOW_PRIVATE_HOSTS="false"
# Optional explicit trusted proxy for outbound MCP OAuth discovery/token calls.
# System HTTP_PROXY/HTTPS_PROXY environment variables are intentionally ignored.
# XAGENT_MCP_OAUTH_PROXY_URL="http://proxy.example.com:8080"

# Trust an ambient HTTP_PROXY/HTTPS_PROXY for outbound public-network fetches
# (webpage fetching, remote SVG inspection, web asset downloads). These paths
# validate and pin the target's DNS-resolved IP to close a DNS-rebinding /
# TOCTOU SSRF window, but a proxy performs its own, independent DNS
# resolution of the target host, reopening that window. Only enable this if
# the configured proxy itself enforces a private-range egress policy. Leave
# disabled (the default) to reject these fetches outright whenever a proxy is
# configured but not explicitly trusted.
# XAGENT_TRUSTED_EGRESS_PROXY="false"

# 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. Also bounds the rendered size of every
# trace category's console log line (not just LLM audit events). 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"

# In-turn tool concurrency: run independent, concurrency-safe tool calls from a
# single ReAct turn in parallel instead of one-by-one. Default off (serial).
# XAGENT_TOOL_PARALLEL_ENABLED="false"
# Max concurrent tool calls per turn batch (kept low to limit API rate-limit
# pressure). Invalid/non-positive values fall back to the default.
# XAGENT_TOOL_MAX_CONCURRENCY="3"

# Out-of-tree task runtime provider hooks use a dedicated process-wide worker
# pool so a blocking provider cannot starve unrelated asyncio.to_thread work.
# Size this for the expected cross-task/provider concurrency. Queue wait has a
# separate timeout and does not consume each hook's execution-time allowance.
# XAGENT_TASK_RUNTIME_HOOK_MAX_WORKERS="8"
# XAGENT_TASK_RUNTIME_HOOK_QUEUE_TIMEOUT_SECONDS="30"

# ===========================================
# Local browser use
# ===========================================
# Controls one visible window of the configured browser on the same host as
# the Xagent backend through `cua-driver mcp`. Tasks bind to an exact browser
# window and never switch silently. Keep disabled on shared/cloud hosts.
# XAGENT_NATIVE_BROWSER_ENABLED="false"
# XAGENT_NATIVE_BROWSER_APP_NAME="Google Chrome"
# XAGENT_BROWSER_CUA_DRIVER_COMMAND="cua-driver"
# XAGENT_BROWSER_CUA_DRIVER_SOCKET=""
# XAGENT_BROWSER_CUA_DRIVER_TIMEOUT_SECONDS="30"
# Number of AX nodes scanned before Xagent prioritizes at most 100 visible,
# actionable elements for model context. A larger scan preserves transient
# menus without sending the full accessibility tree to the model.
# XAGENT_BROWSER_CUA_DRIVER_MAX_ELEMENTS="2000"

# Fallback locale/timezone for browser_use (Playwright) sessions, used when a
# task carries no resolvable locale of its own (the app_locale cookie set by
# the web UI's language switcher). Locale defaults to "en-US"; timezone
# defaults to the host's own system timezone when unset. An invalid value
# raises on first browser-tool use (not at process startup, and not silently
# ignored) -- check the error against the tool call that triggered it, since
# the validation itself lives in src/xagent/config.py, not here.
# XAGENT_BROWSER_TOOL_DEFAULT_LOCALE="en-US"
# XAGENT_BROWSER_TOOL_DEFAULT_TIMEZONE=""

# Context compaction: the conversation is compacted when the estimated context
# size reaches (model context window * ratio). Set a model's context window in
# the model config; models without one fall back to the default below.
# Ratio must be within (0, 1]; invalid values fall back to 0.75.
# XAGENT_COMPACT_THRESHOLD_RATIO="0.75"
# Fallback threshold in tokens when a model has no context window configured.
# XAGENT_COMPACT_THRESHOLD_DEFAULT="32000"

# Checkpoint storage encoding v2: dedup nested DAG/auto contexts, per-record
# tool ledgers, and large system prompts into content-addressed blob tables.
# Decode support is unconditional; this only gates NEW writes. For a mixed
# fleet, roll out in two phases: deploy every instance with "false" first
# (decode-only), then remove the override to start writing v2. Default on.
# XAGENT_CHECKPOINT_ENCODING_V2="true"
# How many checkpoint trace-event rows to keep per task execution. Older rows
# are pruned when a new checkpoint is written (resume only reads the latest
# readable one; a few extras are kept as fallback). "0" disables pruning.
# XAGENT_CHECKPOINT_HISTORY_LIMIT="8"

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

# Google Ads developer token (Optional)
# Required for the Google Ads connector in MCP. Apply for/find this token in
# the Ads API Center of a Google Ads manager (MCC) account:
# https://ads.google.com/aw/apicenter
# This is a single platform-wide token shared by all users who connect the
# Google Ads app (not a per-user secret), analogous to GOOGLE_CLIENT_ID above.
GOOGLE_ADS_DEVELOPER_TOKEN=""

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

# ===========================================
# HubSpot OAuth Configuration (Optional)
# ===========================================
# Required for the HubSpot CRM integration in MCP
# Create a public app at https://developers.hubspot.com/ and configure the
# app's scopes to match the connector:
#   Required: crm.objects.contacts.read, crm.objects.contacts.write,
#     crm.objects.companies.read, crm.objects.companies.write,
#     crm.objects.deals.read, forms
#   Optional (tier-gated - mark these "Optional" in the app's scope
#     configuration, not "Required", or HubSpot refuses to install the app):
#     business-intelligence, marketing-email, marketing.campaigns.read
HUBSPOT_CLIENT_ID=""
HUBSPOT_CLIENT_SECRET=""
# Redirect URI for HubSpot OAuth callback
# Example: http://localhost:8000/api/auth/hubspot/callback
HUBSPOT_REDIRECT_URI=""

# ===========================================
# GitHub OAuth Configuration (Optional)
# ===========================================
# Required for the GitHub integration in MCP (search repos/code, read and
# create issues and pull requests, comment, browse file contents and commit
# history). Create an OAuth App at https://github.com/settings/developers
# (no app review needed -- it works immediately for any GitHub account).
# GitHub OAuth Apps have no scope configuration step of their own -- this
# connector requests read:user repo user:email at authorize time, and
# there is nothing to set up on GitHub's side to match it.
# Note: the GITHUB_ prefix is reserved by GitHub Actions for its own
# runner-provided variables (GITHUB_TOKEN, GITHUB_SHA, etc.) -- setting
# these two as step/workflow env vars in an Actions workflow will be
# rejected. That only affects deployments that configure this service via
# an Actions workflow; a plain .env file or container env is unaffected.
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
# If the OAuth App has "token expiration" enabled, tokens carry a
# refresh_token and expire in ~8 hours; refresh is handled automatically.
# To rotate the client secret: the persisted provider row (admin connector
# settings) wins over this env var for both connect and refresh once it's
# non-empty. Either update the row to the new secret, or clear the row and
# set this var instead -- both connect and refresh fall back to it when the
# row is blank, so clearing it does not break refresh for already-connected
# users.
# Redirect URI for GitHub OAuth callback -- must exactly match the
# "Authorization callback URL" configured for the app. GitHub does not
# enforce port matching for localhost/127.0.0.1, but this value is still
# used verbatim in both the authorize request and the token exchange.
# Example: http://localhost:8000/api/auth/github/callback
GITHUB_REDIRECT_URI=""

# ===========================================
# Meta OAuth Configuration (Optional)
# ===========================================
# Required for Facebook Pages and Instagram integrations in MCP
# Create credentials at https://developers.facebook.com/apps/
META_CLIENT_ID=""
META_CLIENT_SECRET=""
# Redirect URI for Meta OAuth callback
# Example: http://localhost:8000/api/auth/meta/callback
META_REDIRECT_URI=""
# Optional Facebook Login for Business configuration ID. When set, Meta OAuth
# uses config_id instead of a raw scope list, which is required by some Meta app
# configurations for Pages and Instagram permissions.
# IMPORTANT: the permission list is not sent as a `scope` param in this mode -
# it comes entirely from the Login Configuration in the Meta App Dashboard. Any
# permission this connector requests (pages_show_list, pages_read_engagement,
# pages_manage_posts, pages_read_user_content, instagram_basic,
# instagram_content_publish) must also be added to that Login Configuration, or
# users who authorize via config_id will not grant it.
META_CONFIG_ID=""

# ===========================================
# Slack OAuth Configuration (Optional)
# ===========================================
# Required for the Slack integration in MCP (search/read channel, thread, and
# DM history and topics; post messages and thread replies; react to
# messages; upload files; join a public channel when asked to).
# Create an app at https://api.slack.com/apps, add these bot scopes under
# "OAuth & Permissions": chat:write, chat:write.public, channels:read,
# channels:history, channels:join, groups:read, groups:history, im:read,
# im:history, mpim:read, mpim:history, reactions:write, files:write
# Note: chat:write.public also lets the bot post into any public channel
# without being invited — it bypasses Slack's invite gate.
# Leave "Token Rotation" off — bot tokens don't expire, so no refresh is needed.
# Existing connections must be reconnected after adding the new scopes above
# to an already-installed app (Slack does not retroactively grant scopes to
# tokens issued before they were added).
SLACK_CLIENT_ID=""
SLACK_CLIENT_SECRET=""
# Redirect URI for Slack OAuth callback — must also be added under the app's
# "OAuth & Permissions" > "Redirect URLs".
# Example: http://localhost:8000/api/auth/slack/callback
SLACK_REDIRECT_URI=""
# Note: slack_upload_file's allowed-directory allowlist (like the LinkedIn
# connector's equivalent) is scoped to the task workspace automatically by
# the launcher — there is no operator-facing env var for it here.

# ===========================================
# Zoom OAuth Configuration (Optional)
# ===========================================
# Required for the Zoom integration in MCP (meeting lookup, cloud recordings,
# transcripts). Create a "General App" (User Managed) at
# https://marketplace.zoom.us/develop/create and add the scopes:
# meeting:read:meeting, meeting:read:list_meetings, meeting:read:past_meeting,
# cloud_recording:read:list_recording_files, cloud_recording:read:meeting_transcript,
# user:read:user
ZOOM_CLIENT_ID=""
ZOOM_CLIENT_SECRET=""
# Redirect URI for Zoom OAuth callback — must exactly match a URL registered
# in the app's OAuth Allow List.
# Example: http://localhost:8000/api/auth/zoom/callback
ZOOM_REDIRECT_URI=""

# ===========================================
# Intercom OAuth Configuration (Optional)
# ===========================================
# Required for the Intercom integration in MCP (search contacts, review
# conversations, reply to customers). Create an app at
# https://developers.intercom.com/ and, under Authentication, enable OAuth
# and select the permissions this connector needs (Read/write contacts and
# conversations). Intercom does not accept a `scope` parameter on the
# authorize URL — granted permissions come entirely from that Authentication
# configuration, not from anything this app sends.
# One app is expected to cover every workspace region (US/EU/AU): the API
# host (api.intercom.io) auto-routing to the workspace's actual region is
# documented in Intercom's REST API reference. The authorize host
# (app.intercom.com) working the same way for a Public App comes from
# Intercom's own community answer rather than primary docs, and hasn't been
# verified against a live non-US workspace — see builtin_mcp_registry.py's
# intercom provider row for the citation. Unlike Intercom's hosted MCP
# server, which has separate per-region endpoints and no AU support at all,
# this is the reason a local connector was built instead of using that.
INTERCOM_CLIENT_ID=""
INTERCOM_CLIENT_SECRET=""
# Redirect URI for Intercom OAuth callback — must also be added under the
# app's Authentication > Redirect URLs.
# Example: http://localhost:8000/api/auth/intercom/callback
INTERCOM_REDIRECT_URI=""

# ===========================================
# Salesforce OAuth Configuration (Optional)
# ===========================================
# Required for the Salesforce integration in MCP (query/manage accounts,
# contacts, leads, opportunities, and custom objects via SOQL/SOSL). Create a
# Connected App at Setup > App Manager > New Connected App, enable OAuth
# Settings, and select the scopes: api, refresh_token (offline_access),
# openid. The Consumer Key/Secret are under the app's "Manage Consumer
# Details" after saving.
# A free Developer Edition org (https://developer.salesforce.com/signup) is
# enough to create a Connected App and test this connector.
# Note: the authorize/token URLs are hardcoded to login.salesforce.com
# (production). Sandbox orgs authenticate through test.salesforce.com
# instead; there is no env var to switch it, but an admin can hand-edit a
# second oauth_providers row (e.g. "salesforce-sandbox", so both coexist)
# to point at test.salesforce.com, plus a matching second public_mcp_apps
# row with its own app_id/launch_config/env_mapping -- one oauth_providers
# row alone isn't a working connector. Unlike that row's own unused
# userinfo_url column, salesforce.py's USERINFO_URL is a *module-level
# constant* hardcoded to the production host and used unconditionally by
# salesforce_get_current_user on every call -- a sandbox-issued token
# sent there will fail, not silently work. There is currently no way to
# make that one tool sandbox-aware without a code change.
# Newer orgs enforce PKCE on this grant with no per-app opt-out, so the
# login route encrypts the PKCE verifier with ENCRYPTION_KEY (see the
# security section) before embedding it in the signed state token --
# unlike Slack's workspace tokens, this is the first *login-path* use of
# ENCRYPTION_KEY in this codebase, so double check it's actually set
# (not just left to the built-in development-only default) before relying
# on this connector outside local development.
SALESFORCE_CLIENT_ID=""
SALESFORCE_CLIENT_SECRET=""
# Redirect URI for Salesforce OAuth callback — must exactly match a URL
# registered under the Connected App's OAuth Settings > Callback URL.
# Example: http://localhost:8000/api/auth/salesforce/callback
SALESFORCE_REDIRECT_URI=""

# ===========================================
# Deputy OAuth Configuration (Optional)
# ===========================================
# Required for the Deputy integration in MCP (look up employees, view
# rosters/shifts, and read timesheets). Register an OAuth client at
# https://once.deputy.com/my/oauth_clients ("New Oauth Client") to get a
# Client ID/Secret. A free trial account at https://www.deputy.com includes
# a dedicated installation you can use to test this connector.
# Deputy has no fixed API host: each install's actual base URL (e.g.
# acme.au.deputy.com) is returned in the token response as `endpoint` and
# persisted per-connection as UserOAuth.instance_url -- token refresh must
# also go through that same per-install host (once.deputy.com only serves
# the initial code exchange), which tools/config.py's refresh_oauth_token_
# if_needed handles automatically once a connection exists.
DEPUTY_CLIENT_ID=""
DEPUTY_CLIENT_SECRET=""
# Redirect URI for Deputy OAuth callback — must exactly match the URL
# registered on the OAuth client.
# Example: http://localhost:8000/api/auth/deputy/callback
DEPUTY_REDIRECT_URI=""

# ===========================================
# Linear OAuth Configuration (Optional)
# ===========================================
# Required for the Linear integration in MCP (search/manage issues, teams,
# labels, comments, and projects). Create an OAuth application at
# https://linear.app/settings/api/applications (no app review needed — it
# works immediately for any Linear workspace). Linear's app registration has
# no scope-selection field; the read/write scopes this integration needs are
# requested automatically at connect time, nothing to configure here.
LINEAR_CLIENT_ID=""
LINEAR_CLIENT_SECRET=""
# Redirect URI for Linear OAuth callback — must exactly match the
# "Callback URLs" configured for the application.
# Example: http://localhost:8000/api/auth/linear/callback
LINEAR_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.
# The value must name one directory unambiguously: a spelling whose lexical
# reading and whose symlink-resolved reading are different directories -- in
# practice a ".." segment after a symlink -- is refused at startup. Sandbox
# mount identity is lexical while file access resolves symlinks, so such a
# value would put uploads outside the tree the sandbox mounts. Plain symlinks
# are fine. The same rule applies when the root comes from XAGENT_WEB_DIR.
# 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 defaults use standard Botocore retry mode with three total attempts (one
# initial plus two retries) and bounded client timeouts. An explicit
# config_kwargs.retries mapping replaces the default retry mapping.
# 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).
# For a media-streaming ticket's request (see XAGENT_FILE_STREAM_TICKET_TTL_SECONDS
# below), this TTL governs everything after the first redirect hop, so a long
# video's effective playback session is min(ticket TTL, this TTL) -- raising one
# without the other doesn't extend it.
# 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/"

# Lifetime of a short-lived, per-file media-streaming ticket (see
# GET /api/files/stream-tickets/{file_id}). Media elements load this ticket
# directly in a URL, so it is kept far shorter than the user's own access
# token TTL. When XAGENT_FILE_DELIVERY_REDIRECT_ENABLED is also set, see
# XAGENT_FILE_DELIVERY_SIGNED_URL_TTL_SECONDS above for how the two interact.
# XAGENT_FILE_STREAM_TICKET_TTL_SECONDS="600"

# External upload directories for knowledge base file access.
# Comma-separated list of existing directory paths. Symlink aliases authorize
# the physical directory they resolve to. Avoid ambiguous spellings such as
# "symlink/.."; configure the intended directory directly.
# Sandbox-enabled deployments must not place one of these mounts at or below
# the managed <XAGENT_UPLOADS_DIR>/user_<id> subtree. Put shared data elsewhere
# under the uploads root (for example <uploads>/shared) or mount an ancestor.
# XAGENT_EXTERNAL_UPLOAD_DIRS="/path/to/uploads1,/path/to/uploads2"

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

# Built frontend static export served by the backend in single-process
# (pip / uvx) mode (default: $XAGENT_WEB_DIR/frontend_dist). Leave unset unless
# serving a frontend build from a custom location.
# XAGENT_FRONTEND_DIST_DIR=""

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

# Deadline in seconds for a single knowledge base collection listing scan used by
# GET /api/kb/collections. Applies per scan (personal plus each team-KB owner), not
# to the whole request. Raise it for very large collections; exceeding it returns 503.
# XAGENT_KB_COLLECTIONS_TIMEOUT_SECONDS="30"

# Maximum time in seconds to poll a Google Drive long-running export during
# POST /api/kb/ingest-cloud. The final file transfer can extend the request beyond
# this value, so reverse-proxy timeouts must also allow for transfer time.
# XAGENT_GOOGLE_DRIVE_DOWNLOAD_TIMEOUT_SECONDS="600"

# 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
# ===========================================
# Deployment envelope: the sandbox manager's in-process caches (activity
# ref-counts, lease providers, reconcile budget) assume a single backend
# process per Docker daemon. Both console-script entrypoints (xagent's
# `xagent.web.__main__` and xagent-saas's `docker/entrypoint.sh` ->
# `xagent_saas/__main__.py`) start uvicorn without `workers=`, so this holds
# for the shipped deployment paths; `xagent.web.run_server(**kwargs)` can
# still be called with `workers=N` by an embedder, which this manager does
# not detect or reject.
#
# Enable/disable sandbox execution environment (default: false)
# SANDBOX_ENABLED="false"

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

# Required when sandbox execution uses the Docker implementation. The Docker
# Compose sibling overlay sets this to COMPOSE_PROJECT_NAME automatically.
# Non-Compose deployments (pip/systemd) must choose one stable, unique value
# per deployment.
# XAGENT_SANDBOX_NAMESPACE="my-deployment"

# 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.
# When set, this must be an absolute Docker-host path. Relative paths and "~"
# are rejected rather than being interpreted in the backend container.
# XAGENT_SANDBOX_HOST_STORAGE_ROOT=""

# Set automatically for the sandbox tool runner process; never set it yourself.
# It tells workspace file registration that this process has no database or
# object storage credentials, so the host process registers sandbox outputs
# instead. Setting it on a host process makes that process mint throwaway ids
# for every file it registers, so nothing it produces is ever persisted. Read
# once at process start, so changing it at runtime has no effect.
# XAGENT_SANDBOX_TOOL_RUNNER=""

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

# Max concurrent worker sandboxes per user/task lifecycle. This only affects
# sandboxed tools that explicitly opt into concurrency-safe execution.
# Invalid/non-positive values fall back to the default.
# XAGENT_SANDBOX_MAX_CONCURRENCY="3"

# ===========================================
# Sandbox Idle Reclamation
# ===========================================
# Idle TTL in seconds after which sandbox containers with no active tasks are
# deleted by a background sweep (default: unset — containers live forever,
# matching previous behavior).
#
# Reclamation deletes the container. Workspace data lives on bind mounts and
# survives; the sandbox is transparently recreated on next use (cold-start
# latency only). Anything written OUTSIDE the mounted workspace/uploads paths
# is lost: lazily installed pip packages (reinstalled on demand), files under
# /tmp or $HOME inside the container. Containers found at backend startup
# with no recorded activity are treated as idle since startup and reclaimed
# one TTL later.
# XAGENT_SANDBOX_IDLE_TTL="86400"

# Interval in seconds between idle sweep runs (default: 60). Only meaningful
# when XAGENT_SANDBOX_IDLE_TTL is set.
# XAGENT_SANDBOX_SWEEP_INTERVAL="60"

# ===========================================
# Sandbox Capacity Limit
# ===========================================
# Maximum number of concurrently existing sandbox containers (default: unset
# — no cap, matching previous behavior). The cap counts all managed
# containers including per-lifecycle workers; the transient warmup container
# is excluded.
#
# When a new sandbox is requested at the cap, the least-recently-used idle
# sandbox (no active tasks) is deleted to make room. If nothing is evictable
# (all sandboxes busy), a task's primary sandbox request fails at task
# admission with a clear capacity error by default instead of silently
# running on the host. A worker sandbox for a concurrency-safe tool that
# cannot fit under the cap (a task's own primary occupies a slot and is
# never evicted to make room for its workers) degrades to running on the
# task's primary sandbox with a warning log — reduced isolation, but the
# tool keeps working mid-task.
#
# Size the cap for full worker isolation: allow roughly expected concurrent
# primaries x (1 + XAGENT_SANDBOX_MAX_CONCURRENCY) containers.
#
# Note: the ref-count and cap are per-backend-process state. Deployments
# running multiple backend workers/replicas against one Docker daemon get
# approximate enforcement only.
# XAGENT_SANDBOX_MAX_CONTAINERS="20"

# Allow tasks to fall back to local (host) execution when the sandbox cap is
# reached and nothing is evictable (default: false — reject the task).
# Enable only if you prefer availability over strict sandboxing; sandbox
# service unavailability keeps its local fallback regardless of this flag.
# XAGENT_SANDBOX_ALLOW_LOCAL_FALLBACK_ON_CAPACITY="false"

# ===========================================
# 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.
#   - dst must not equal or fall below the managed
#     <XAGENT_UPLOADS_DIR>/user_<id> subtree. A nested bind would shadow the
#     task workspace. Use a destination elsewhere or mount an ancestor.
#
# 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"

# ===========================================
# Interaction Rollout Configuration
# ===========================================
# Default-off gate controlling whether tasks may publish native interaction
# rows. One of: legacy, read, native. Stays "legacy" (no native rows
# produced) unless explicitly switched.
# XAGENT_INTERACTION_PROTOCOL_MODE="legacy"

# Comma-separated list of task sources allowed to publish native rows when
# mode is "native" (ignored otherwise). Each entry must be one of: internal,
# sdk, a2a, trigger, widget, shared_link, channel. Native mode requires at
# least one entry here.
# XAGENT_INTERACTION_NATIVE_SOURCES=""