Hugging Face's logo

Spaces:
somratpro
/
huggingFlow
Running

App Files Community
huggingFlow / README.md
somratpro's picture
somratpro
docs: add duplicate space button, secrets frontmatter, support section
0b075c6
preview code
|
raw
history blame contribute delete
14.4 kB
---
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."
---
<div align="center">
# 🦌 HuggingFlow
**[DeerFlow](https://github.com/bytedance/deer-flow) research agent — one-click deploy on Hugging Face Spaces**
[![HF Space](https://img.shields.io/badge/🤗%20Hugging%20Face-Space-yellow)](https://huggingface.co/spaces/somratpro/HuggingFlow)
[![GitHub](https://img.shields.io/badge/GitHub-somratpro%2FHuggingFlow-181717?logo=github)](https://github.com/somratpro/HuggingFlow)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Docker](https://img.shields.io/badge/docker-single--container-2496ED?logo=docker)](Dockerfile)
*Self-hosted deep-research AI · multi-provider LLM · streaming SSE · dataset backup*
</div>
---
## Table of Contents
- [What is HuggingFlow?](#what-is-huggingflow)
- [Features](#features)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
 - [Required Secrets](#required-secrets)
 - [Optional Variables](#optional-variables)
- [LLM Providers](#llm-providers)
- [Search Tools](#search-tools)
- [Cloudflare Proxy](#cloudflare-proxy)
- [Data Backup](#data-backup)
- [Stay Alive (Keep-Awake)](#stay-alive-keep-awake)
- [Architecture](#architecture)
- [Local Development](#local-development)
- [Troubleshooting](#troubleshooting)
- [More Projects](#more-projects)
- [Contributing](#contributing)
- [License](#license)
---
## What is HuggingFlow?
HuggingFlow wraps [DeerFlow](https://github.com/bytedance/deer-flow) (ByteDance's open-source deep-research agent) into a single Docker container that runs natively on [Hugging Face Spaces](https://huggingface.co/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
[![Duplicate this Space](https://huggingface.co/datasets/huggingface/badges/resolve/main/duplicate-this-space-xl.svg)](https://huggingface.co/spaces/somratpro/HuggingFlow?duplicate=true)
### Step 2 — Add required secrets
In your new Space → **Settings → Variables and Secrets**, add at minimum:
| Secret | Description |
|--------|-------------|
| `LLM_MODEL` | Model in `provider/model-name` format — e.g. `openai/gpt-4o` |
| `LLM_API_KEY` | API key for the chosen provider |
> [!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
| Secret | Description |
|--------|-------------|
| `LLM_MODEL` | Model in `provider/model-name` format — see [LLM Providers](#llm-providers) |
| `LLM_API_KEY` | API key for the chosen provider |
### Optional Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `SERPER_API_KEY` | — | Google Search via Serper — strongly recommended over DuckDuckGo |
| `TAVILY_API_KEY` | — | Alternative web search (used if Serper not set) |
| `JINA_API_KEY` | — | Better web page fetching via Jina AI |
| `AUTH_JWT_SECRET` | auto-generated | JWT signing secret — set this to keep sessions alive across restarts |
| `HF_TOKEN` | — | Your HF token — enables dataset backup/restore |
| `BACKUP_DATASET_NAME` | `huggingflow-backup` | HF dataset repo name for backups (created automatically) |
| `CUSTOM_BASE_URL` | — | OpenAI-compatible API base URL for any custom/self-hosted provider |
| `SYNC_INTERVAL` | `600` | Seconds between HF Dataset backup syncs |
| `BACKEND_READY_TIMEOUT` | `120` | Seconds to wait for backend startup |
| `FRONTEND_READY_TIMEOUT` | `120` | Seconds to wait for frontend startup |
| `CLOUDFLARE_WORKERS_TOKEN` | — | Cloudflare API token — enables outbound proxy + keep-awake cron |
| `CLOUDFLARE_PROXY_URL` | — | Existing Cloudflare Worker URL (skip auto-setup) |
---
## LLM Providers
Set `LLM_MODEL` to `provider/model-name`:
| Provider | Example `LLM_MODEL` | Notes |
|----------|---------------------|-------|
| **OpenAI** | `openai/gpt-4o` | Default provider |
| **Anthropic** | `anthropic/claude-sonnet-4-5` | Extended thinking supported |
| **Google Gemini** | `google/gemini-2.5-flash` | Extended thinking supported |
| **DeepSeek** | `deepseek/deepseek-chat` | Extended thinking supported |
| **Groq** | `groq/llama-3.3-70b-versatile` | Fast inference |
| **Mistral** | `mistral/mistral-large-latest` | |
| **xAI / Grok** | `xai/grok-3-beta` | |
| **OpenRouter** | `openrouter/anthropic/claude-3-5-sonnet` | Access 200+ models |
| **Qwen / Alibaba** | `qwen/qwen-max` | DashScope compatible |
| **Moonshot / Kimi** | `moonshot/moonshot-v1-128k` | |
| **Custom OpenAI-compat** | `openai/your-model` + `CUSTOM_BASE_URL` | Any self-hosted endpoint |
> **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:
| Tool | Key | Quality | Cost |
|------|-----|---------|------|
| **Serper** | `SERPER_API_KEY` | ⭐⭐⭐ (real Google) | ~$0.001/query |
| **Tavily** | `TAVILY_API_KEY` | ⭐⭐ | free tier available |
| **DuckDuckGo** | none needed | ⭐ | free, rate-limited |
Serper is strongly recommended for research quality. Sign up at [serper.dev](https://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:**
| Port | Service | Exposed |
|------|---------|---------|
| 7860 | health-server.js | ✅ public (HF Spaces) |
| 7861 | nginx | internal only |
| 8001 | FastAPI backend | internal only |
| 3000 | Next.js frontend | internal only |
**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
```bash
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:**
| Route | Description |
|-------|-------------|
| `/` | Status dashboard |
| `/workspace` | DeerFlow research UI |
| `/setup` | Admin account creation (first boot only) |
| `/api/health` | Backend health (JSON) |
| `/docs` | Swagger API reference |
| `/redoc` | ReDoc API reference |
---
## 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](https://github.com/somratpro) — all free, one-click deploy on HF Spaces:
| Project | What it runs | HF Space | GitHub |
|---------|-------------|----------|--------|
| **HuggingClip** | Paperclip — AI agent orchestration | [Space](https://huggingface.co/spaces/somratpro/HuggingClip) | [Repo](https://github.com/somratpro/HuggingClip) |
| **HuggingClaw** | OpenClaw — Claude Code in the browser | [Space](https://huggingface.co/spaces/somratpro/HuggingClaw) | [Repo](https://github.com/somratpro/HuggingClaw) |
| **HuggingMes** | Hermes — self-hosted agent gateway | [Space](https://huggingface.co/spaces/somratpro/HuggingMes) | [Repo](https://github.com/somratpro/HuggingMes) |
| **Hugging8n** | n8n — workflow & automation platform | [Space](https://huggingface.co/spaces/somratpro/Hugging8n) | [Repo](https://github.com/somratpro/Hugging8n) |
| **HuggingPost** | Postiz — social media scheduler | [Space](https://huggingface.co/spaces/somratpro/HuggingPost) | [Repo](https://github.com/somratpro/HuggingPost) |
---
## ❤️ 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](CONTRIBUTING.md) for guidelines.
```
Fork → branch → commit → PR
```
---
## License
MIT — see [LICENSE](LICENSE).
DeerFlow is © ByteDance, licensed under MIT.
---
<div align="center">
 <sub>Built with ❤️ by <a href="https://github.com/somratpro">somratpro</a> · Powered by <a href="https://github.com/bytedance/deer-flow">DeerFlow</a></sub>
</div>