---
title: "Deploy DeerFlow"
description: "AI assistant that researches topics and writes reports for you"
category: "AI/ML"
url: https://railway.com/deploy/deer-flow
---

# Deploy DeerFlow

AI assistant that researches topics and writes reports for you

**[Deploy DeerFlow on Railway](https://railway.com/template/deer-flow)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deer-flow/manifest.json

- **Creator:** A3A
- **Category:** AI/ML
- **Total deploys:** 1

## Template content

### gateway https://raw.githubusercontent.com/gridalpha/deerflow-railway/main/assets/deerflow-light.svg

- **Source:** https://github.com/gridalpha/deerflow-railway
- **Health check:** /health

### deerflow https://raw.githubusercontent.com/gridalpha/deerflow-railway/main/assets/deerflow-light.svg

- **Source:** https://github.com/gridalpha/deerflow-railway
- **Health check:** /healthz
- **Public domain:** Yes

### frontend https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/nextjs-light.svg

- **Image:** ghcr.io/bytedance/deer-flow-frontend:latest

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# 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](https://github.com/gridalpha/deerflow-railway).

![Diagram of the DeerFlow proxy, gateway, frontend and Postgres services](https://res.cloudinary.com/rroe4rtk/image/upload/v1787440230/deerflow-architecture.png)

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

![DeerFlow workspace with the prompt composer and skill shortcuts](https://res.cloudinary.com/rroe4rtk/image/upload/v1787440232/deerflow-workspace.png)

![DeerFlow settings listing the bundled agent skills with toggles](https://res.cloudinary.com/rroe4rtk/image/upload/v1787440234/deerflow-agent-skills.png)

![DeerFlow chats list holding two saved research conversations](https://res.cloudinary.com/rroe4rtk/image/upload/v1787440238/deerflow-chats.png)

## 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](https://github.com/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

| Variable | Description | Required |
|----------|-------------|----------|
| `DEERFLOW_ADMIN_EMAIL` | Admin account created at first boot | Yes |
| `DEERFLOW_ADMIN_PASSWORD` | Password for it, 8+ characters | Yes |
| `AUTH_JWT_SECRET` | Signs session tokens; changing it signs everyone out | Yes |
| `BETTER_AUTH_SECRET` | Frontend session signing key, 32+ characters | Yes |
| `LLM_API_KEY` | Key for the OpenAI-compatible provider | No |
| `LLM_BASE_URL` / `LLM_MODEL` | Provider endpoint and model | No |
| `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | Keys for the other model entries | No |
| `DEERFLOW_ALLOW_REGISTRATION` | `true` opens public sign-up | No |
| `JINA_API_KEY` / `TAVILY_API_KEY` | Better page fetching and search | No |

### Deployment Dependencies

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

## Hardware Requirements for Self-Hosting DeerFlow

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

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPU | 4–8 vCPU |
| RAM | 4 GB | 8–16 GB |
| Storage | 5 GB volume | 20 GB+ for heavy file generation |
| Database | PostgreSQL 14+ | Railway-managed Postgres |
| Runtime | Python 3.12, Node 22 | Same, from the images |

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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/deer-flow