Deploy DeerFlow

Deploy and Host DeerFlow on Railway

DeerFlow is ByteDance's open-source super-agent harness. Give it a goal in plain language and a lead agent plans the work, searches the web, reads and writes files, delegates to sub-agents, and returns a finished piece of work — a cited briefing, a slide deck, a chart, a podcast script. Its abilities come from Markdown skills, twenty-two of which ship in the box, and it is model-agnostic: OpenAI, Anthropic, Gemini, DeepSeek, or your own vLLM endpoint. MIT-licensed, and number one on GitHub Trending when version 2 landed.

Deploy DeerFlow on Railway and the four services it needs are wired together for you. An nginx edge service takes the public domain and splits it between the Next.js frontend and the FastAPI gateway, since DeerFlow serves UI and API on one origin. The gateway runs the agent and keeps threads, checkpoints, users, and run events in managed Postgres, with a volume for thread workspaces, uploads, and memory. Self-host DeerFlow this way and you skip the parts everyone gets wrong: the config file, the skills directory, and the routing table. Images build from gridalpha/deerflow-railway.

Getting Started with DeerFlow on Railway

Set DEERFLOW_ADMIN_EMAIL and DEERFLOW_ADMIN_PASSWORD before you click Deploy: the gateway creates that admin account as soon as it is healthy, closing the window in which a stranger could claim the instance from the setup page. Open the public URL, sign in, and you are in the workspace. Add a model key next — LLM_API_KEY for any OpenAI-compatible provider, or ANTHROPIC_API_KEY or GEMINI_API_KEY — since everything else works out of the box but a run needs a model. Then type a real task into the composer — research the current state of solid-state batteries and write me a briefing with sources — and watch it stream back. Web search works immediately through DuckDuckGo with no key. Settings → Skills lists the twenty-two bundled skills, so you can toggle off any you would rather the agent not reach for; conversations under Chats survive restarts.

About Hosting DeerFlow

Version 2 is a ground-up rewrite of what began as a deep-research framework. Teams self-host it when the research is sensitive, when they want their own model contract rather than a per-seat subscription, or when they need private skills.

• Skills — Markdown files teaching a workflow: deep research, literature review, charts, slides, podcasts, front-end design.
• Sub-agents — bounded work delegated to children with their own turn and time budgets, so long tasks outlive one context window.
• Long-term memory — facts learned across conversations feed later prompts.
• Any model, plus MCP — the OpenAI protocol, native Anthropic and Gemini, external tools over the Model Context Protocol, and custom agents with their own prompt and tools.

deerflow is the only public service; it owns the domain and routes /api/* to the gateway, everything else to the frontend. gateway runs the agent loop and streams results. frontend is the Next.js UI. Postgres stores users, threads, checkpoints, and run traces; the gateway's volume holds each thread's files.

Why Deploy DeerFlow on Railway

Everything the four-container stack needs is pre-wired.

• No Docker Compose, config files, or volume plumbing to write
• Private networking between proxy, gateway, frontend, and database
• Managed Postgres plus a persistent volume for agent files
• Managed TLS and a custom domain
• Self-registration closed by default, so the instance stays yours

Common Use Cases

• Market and competitor research — ask a question, get a cited briefing, not thirty browser tabs.
• Literature reviews — the systematic-review and academic-paper skills structure papers into summaries.
• Internal reporting — turn a CSV or database export into charts and slides.
• A team research assistant — one deployment, your key, no history leaving your infra.

Dependencies for DeerFlow

• DeerFlow gateway — ghcr.io/bytedance/deer-flow-backend:latest, rebuilt from gridalpha/deerflow-railway with config, skills, and the Postgres driver baked in.
• DeerFlow frontend — ghcr.io/bytedance/deer-flow-frontend:latest, unmodified.
• Edge proxy — nginx:1.29-alpine, ByteDance's routing table.
• PostgreSQL — Railway-managed: users, threads, checkpoints, runs.

Environment Variables Reference

Deployment Dependencies

• Source: github.com/bytedance/deer-flow (MIT)
• Images: ghcr.io/bytedance/deer-flow-backend, ghcr.io/bytedance/deer-flow-frontend
• Docs: deerflow.tech

Hardware Requirements for Self-Hosting DeerFlow

The heavy lifting happens at your model provider, so the containers mostly wait on network.

A single user is comfortable at the minimum; several people running long tasks at once is where the extra CPU and memory matter.

How to Self-Host DeerFlow Outside Railway

DeerFlow ships a Makefile wrapping Docker Compose. Clone the repo, run the setup wizard to pick a model provider and write config.yaml, then bring the stack up — shell:

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup          # interactive: model provider, search, sandbox mode
make up             # builds images, starts nginx + frontend + gateway + redis

It binds 127.0.0.1:2026 on purpose — the agent can execute code, so ByteDance ships it loopback-only. Put authentication in front before exposing it. For Postgres instead of the default SQLite file, add this YAML to config.yaml and set DATABASE_URL:

checkpointer:
  type: postgres
  connection_string: $DATABASE_URL
database:
  backend: postgres
  postgres_url: $DATABASE_URL

Both blocks are needed: the store holding your thread list reads the older checkpointer key, so setting only database leaves conversations in memory, where a restart loses them.

How Much Does DeerFlow Cost to Self-Host?

DeerFlow is free and MIT-licensed — no paid tier, no seat limits, no hosted edition to upsell you. On Railway you pay only for compute, Postgres, and the volume. The real cost is your model provider: every run spends tokens against your key, and long tasks with many sub-agents spend a lot. Pointing LLM_BASE_URL at a cheaper OpenAI-compatible provider, or a local vLLM server, is the usual fix.

FAQ

What is DeerFlow? An open-source super-agent harness from ByteDance. A lead agent plans a task, searches the web, writes files, and delegates to sub-agents, producing research reports, slide decks, charts, and podcasts. MIT-licensed, and model-agnostic.

What does this Railway template deploy? Four services: an nginx edge proxy holding the public domain, the FastAPI gateway running the agent, the Next.js frontend, and managed PostgreSQL. The gateway also gets a volume for the files agents write.

Why does the template include a Postgres database? DeerFlow's default SQLite file lives in the container and disappears on every redeploy. Postgres holds users, conversations, checkpoints, and run traces, so restarts leave everything intact.

Do I need an API key to use self-hosted DeerFlow? It deploys and you can sign in without one, but agent runs need a model. Set LLM_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY. Web search works without a key through DuckDuckGo.

How does DeerFlow compare to Manus or OpenAI Deep Research? Those are polished, hosted for you, tied to their own model. DeerFlow is MIT-licensed, self-hostable, and model-agnostic — pick it when the data must stay on your side, or the agent has to learn a workflow only your company has.

Can other people sign up on my DeerFlow instance? No. Public registration is off, so only the admin account created at deploy time exists — set DEERFLOW_ALLOW_REGISTRATION to true on the proxy service for an open instance. Host shell access for the agent is off too, matching upstream.