.env.example

# ============================================================================
# HuggingFlow — DeerFlow Research Agent on Hugging Face Spaces
# Configuration Reference
# ============================================================================
# Copy this file to .env for local Docker development.
# On HF Spaces, set these as Secrets in Settings → Variables and Secrets.
# NEVER commit your .env file — it contains real credentials.
# ============================================================================

# ============================================================================
# LLM Provider (REQUIRED)
# ============================================================================

# Model in "provider/model-name" format.
# See README for full provider list.
LLM_MODEL=openai/gpt-4o

# API key for the chosen provider.
LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# ============================================================================
# Search Tools (Optional — highly recommended)
# ============================================================================

# Serper — real Google Search results. 2,500 free queries/month.
# https://serper.dev
# SERPER_API_KEY=xxxxxxxxxxxxxxxxxxxx

# Tavily — alternative web search with free tier.
# https://tavily.com
# TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxx

# Jina AI — better web page fetching and reading.
# https://jina.ai
# JINA_API_KEY=jina_xxxxxxxxxxxxxxxxxxxx

# ============================================================================
# Authentication & Security
# ============================================================================

# JWT signing secret for DeerFlow auth. Sessions survive restarts if this is set.
# Generate: openssl rand -base64 32
# AUTH_JWT_SECRET=your-random-secret-here-minimum-32-characters

# ============================================================================
# Data Persistence (Optional — required for threads to survive restarts)
# ============================================================================

# Your Hugging Face API token (needs Write access).
# https://huggingface.co/settings/tokens
# HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# HF Dataset repo name for backups (auto-created as private).
# Will be: {your-hf-username}/{BACKUP_DATASET_NAME}
BACKUP_DATASET_NAME=huggingflow-backup

# How often to sync to HF Dataset (seconds). Default: 10 minutes.
SYNC_INTERVAL=600

# ============================================================================
# Custom / Self-hosted LLM (Optional)
# ============================================================================

# OpenAI-compatible base URL for any custom or self-hosted endpoint.
# When set, uses LLM_API_KEY as the API key and LLM_MODEL as the model name.
# CUSTOM_BASE_URL=https://your-llm-endpoint.example.com/v1

# ============================================================================
# Cloudflare Integration (Optional)
# ============================================================================

# Cloudflare API token with Workers Edit permission.
# Enables: (1) outbound proxy Worker — bypasses HF Spaces IP blocks on some APIs.
#          (2) keep-awake cron Worker — pings /health every 10 min to prevent sleep.
# https://dash.cloudflare.com/profile/api-tokens
# CLOUDFLARE_WORKERS_TOKEN=your_cloudflare_api_token

# Skip auto-setup and use an existing Cloudflare Worker URL directly.
# CLOUDFLARE_PROXY_URL=https://your-worker.your-subdomain.workers.dev

# ============================================================================
# Startup Timeouts (Optional)
# ============================================================================

# Max seconds to wait for the DeerFlow backend (FastAPI) to start.
BACKEND_READY_TIMEOUT=120

# Max seconds to wait for the DeerFlow frontend (Next.js) to start.
FRONTEND_READY_TIMEOUT=120

# ============================================================================
# HuggingFace Spaces — Automatically injected by the platform
# ============================================================================

# These are set automatically by HF Spaces at runtime. Do not set manually.
# SPACE_ID=your-username/your-space-name
# SPACE_HOST=your-username-your-space-name.hf.space
# SPACE_AUTHOR_NAME=your-hf-username

# ============================================================================
# Privacy / Telemetry
# ============================================================================

# DeerFlow is self-hosted — no external telemetry. These are informational only.
DO_NOT_TRACK=1