title: HuggingFlow
emoji: 🦌
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
secrets:

• name: LLM_MODEL
  description: "Model in provider/model-name format — e.g. openai/gpt-4o, anthropic/claude-sonnet-4-5, google/gemini-2.5-flash"
• name: LLM_API_KEY
  description: API key for the chosen LLM provider.
• name: HF_TOKEN
  description: Hugging Face token (write access) — enables thread backup/restore to a private HF Dataset.
• name: SERPER_API_KEY
  description: "Serper API key for real Google Search results (recommended). Free tier: 2,500 queries/month."
• name: AUTH_JWT_SECRET
  description: "JWT signing secret — keeps sessions alive across restarts. Generate: openssl rand -base64 32"
• name: CLOUDFLARE_WORKERS_TOKEN
  description: "Cloudflare API token — auto-creates an outbound proxy Worker and a keep-awake cron Worker."

🦌 HuggingFlow

DeerFlow research agent — one-click deploy on Hugging Face Spaces

⚠️ WARNING: USING THIS PROJECT MAY LEAD TO THE SUSPENSION OF YOUR HUGGINGFACE ACCOUNT.

Self-hosted deep-research AI · multi-provider LLM · streaming SSE · dataset backup

Table of Contents

• What is HuggingFlow?
• Features
• Quick Start
• Configuration
  • Required Secrets
  • Optional Variables
• LLM Providers
• Search Tools
• Cloudflare Proxy
• Data Backup
• Stay Alive (Keep-Awake)
• Architecture
• Local Development
• Troubleshooting
• More Projects
• Contributing
• License

What is HuggingFlow?

HuggingFlow wraps DeerFlow (ByteDance's open-source deep-research agent) into a single Docker container that runs natively on Hugging Face Spaces.

Zero infra. Duplicate the Space, add your API keys, done — your own private research agent is live.

DeerFlow conducts multi-step research: it queries search engines, fetches web pages, synthesises findings across sources, and produces structured reports — all driven by the LLM you choose.

Features

• 🚀 One-click deploy — duplicate the HF Space, add secrets, done
• 🧠 Multi-provider LLM — OpenAI, Anthropic, Google Gemini, DeepSeek, Groq, Mistral, xAI, OpenRouter, Qwen, Moonshot, any OpenAI-compatible endpoint
• 🔍 Pluggable search — Serper (Google), Tavily, or DuckDuckGo (no key needed)
• 💾 Dataset backup — threads auto-sync to a private HF Dataset; restored on restart
• 🌐 Cloudflare outbound proxy — route backend traffic through a Cloudflare Worker (beats HF Spaces IP blocks on some APIs)
• ⏰ Keep-Awake cron — Cloudflare Worker pings /health on a schedule to prevent cold starts
• 📊 Live dashboard — status page at / with service health, model, search, backup and keep-awake tiles
• 🔒 Auth built-in — DeerFlow v2 JWT auth; create admin at /setup on first boot
• ⚡ Pre-built images — no source compilation; pulls official GHCR images for sub-5-minute builds
• 📡 Streaming SSE — real-time agent output streamed to the browser

Quick Start

Step 1 — Duplicate this Space

Step 2 — Add required secrets

In your new Space → Settings → Variables and Secrets, add at minimum:

[!TIP]
Add HF_TOKEN (a token with write access to your account) to enable thread backup persistence. Without it, all research threads are lost on restart.

Step 3 — Wait for build

First build pulls pre-built GHCR images — takes ~5 minutes. Subsequent restarts are instant (no rebuild).

Step 4 — Create your admin account

Visit https://<your-space>.hf.space/setup → create username + password.

Step 5 — Start researching

Open /workspace — you're live 🎉

Configuration

Required Secrets

Optional Variables

LLM Providers

Set LLM_MODEL to provider/model-name:

Tip: Models with extended thinking (Anthropic, Gemini, DeepSeek) produce higher-quality research plans but use more tokens.

Search Tools

DeerFlow uses web search as its primary information source. Configure in priority order:

Serper is strongly recommended for research quality. Sign up at serper.dev — 2,500 free queries/month.

Cloudflare Proxy

HF Spaces shares IPs that some APIs block. The Cloudflare outbound proxy routes backend HTTP requests through a Cloudflare Worker, giving you a clean egress IP.

Setup:

1. Get a Cloudflare API token with Workers Edit permission
2. Set CLOUDFLARE_WORKERS_TOKEN in your Space secrets
3. On next start, cloudflare-proxy-setup.py auto-creates the Worker and sets CLOUDFLARE_PROXY_URL

Or manually provide CLOUDFLARE_PROXY_URL if you have an existing Worker.

Data Backup

By default threads are stored in SQLite inside the container — lost on restart.

Enable persistent backup with HF Datasets:

1. Set HF_TOKEN to a token with Write access to your profile
2. Optionally set BACKUP_DATASET_NAME (default: huggingflow-backup)
3. The dataset is created automatically (private) on first sync

What's backed up: SQLite database (threads, messages, uploads index), workspace files.

Sync schedule: every SYNC_INTERVAL seconds (default 10 min) + on graceful shutdown + on startup (restore).

Stay Alive (Keep-Awake)

Free HF Spaces pause after ~15 minutes of inactivity. Fix it with a Cloudflare Worker cron:

1. Set CLOUDFLARE_WORKERS_TOKEN (same token as proxy setup)
2. cloudflare-keepalive-setup.py creates a Worker that pings /health every 10 minutes
3. Status shown in the dashboard Keep Awake tile

Check KEEPALIVE_STATUS_FILE (/tmp/huggingflow-cloudflare-keepalive-status.json) for current state.

Architecture

Browser
  │
  ▼  :7860
health-server.js  ──── /          → status dashboard (HTML)
  │               ──── /health    → JSON health check
  │               ──── /status    → JSON full status
  │               ──── /*         → proxy to nginx
  │
  ▼  :7861
nginx
  │  /api/langgraph/*  → rewrite → /api/*  → backend :8001
  │  /api/*            →                   → backend :8001
  │  /health           →                   → backend :8001/health
  │  /docs /redoc      →                   → backend :8001
  │  /*                →                   → frontend :3000
  │
  ├─▶ :8001  FastAPI (uvicorn)  — DeerFlow gateway, agents, auth, SQLite
  └─▶ :3000  Next.js            — DeerFlow UI (server-side rendered)

Port map:

Images used:

• ghcr.io/bytedance/deer-flow-backend:latest — pre-built Python backend + .venv
• ghcr.io/bytedance/deer-flow-frontend:latest — pre-built Next.js + node_modules
• No source compilation — build time ~5 min instead of 30+ min

Local Development

git clone https://github.com/somratpro/HuggingFlow
cd HuggingFlow

# Build
docker build -t huggingflow .

# Run (set your own keys)
docker run -p 7860:7860 \
  -e LLM_MODEL=openai/gpt-4o \
  -e LLM_API_KEY=sk-... \
  -e SERPER_API_KEY=... \
  huggingflow

Open http://localhost:7860 for the dashboard, http://localhost:7860/setup to create your admin account, then http://localhost:7860/workspace.

Useful routes:

Troubleshooting

"Application error" on /workspace or /setup

The pre-built frontend requires DEER_FLOW_TRUSTED_ORIGINS to be set explicitly. start.sh handles this automatically. If you see this error in a custom setup, ensure the env var is set before starting Next.js.

Build takes 30+ minutes / OOMKilled

Ensure Docker has ≥4 GB RAM. HuggingFlow uses pre-built images specifically to avoid compilation. If you're rebuilding from source, add NODE_OPTIONS=--max-old-space-size=3072.

DuckDuckGo returning no results

DuckDuckGo rate-limits aggressively from shared IPs. Set SERPER_API_KEY or TAVILY_API_KEY.

Threads lost after restart

Set HF_TOKEN and BACKUP_DATASET_NAME to enable dataset sync. Without it, storage is ephemeral.

Space goes to sleep

Set CLOUDFLARE_WORKERS_TOKEN to enable the keep-awake cron. Alternatively, upgrade to a paid HF Space tier.

Backend health shows not_authenticated

Normal — DeerFlow v2 protects all /api/* routes. The public health endpoint is /health (no auth). nginx routes /health → backend:8001/health.

More Projects

Similar projects by @somratpro — all free, one-click deploy on HF Spaces:

❤️ Support

If HuggingFlow saves you time, consider buying me a coffee to keep the projects alive!

USDT (TRC-20 / TRON network only)

TELx8TJz1W1h7n6SgpgGNNGZXpJCEUZrdB

[!WARNING]
Send USDT on TRC-20 network only. Sending other tokens or using a different network will result in permanent loss.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Fork → branch → commit → PR

License

MIT — see LICENSE.

DeerFlow is © ByteDance, licensed under MIT.