DeerFlow
A DeerFlow first run with a small, checkable assignment
Prepare the documented local prerequisites, select restrictive execution settings and evaluate a report without granting unnecessary external capabilities.
What you will learn
- Start with the documented environment, not a guessed command
- Limit the first assignment to owned inputs
- Observe a run and grade its artifact
Before you start
- Basic Python, HTTP and container concepts
- An owned task with explicit acceptance criteria
Explain the chapter’s implementation boundary and apply its checklist or isolated helper exercise.
Key takeaways
- Validate the shell and both application runtimes.
- Use a tiny owned fixture before adding integrations.
- Check the artifact independently of service health.
Start with the documented environment, not a guessed command
The pinned README uses make check to verify Node.js 22+, pnpm, uv and nginx, then make install for backend and frontend dependencies. make setup opens an interactive configuration wizard that writes config.yaml and credentials to .env. These commands change the local environment and can install hooks; review them in a disposable checkout before execution.
Windows deserves an explicit caveat: this revision documents Git Bash for its bash-based service scripts, not native PowerShell or cmd.exe, and does not guarantee WSL compatibility. The Python requirement comes from the backend manifest. Do not interpret a Python executable on PATH as proof that the frontend, shell utilities and chosen sandbox are also ready.
Limit the first assignment to owned inputs
Use two small documents you are allowed to process, with a few known facts and one deliberate disagreement. Ask the agent to produce a comparison that cites the relevant input and marks the disagreement as unresolved. No browser account, public posting, payment method or production repository is needed to learn whether the basic workflow is useful.
Choose sandbox mode and file-write permissions deliberately in setup. Leave host shell execution disabled for untrusted material, and do not mount personal CLI credential directories just to make the first run convenient. The production configuration separates those mounts into an opt-in overlay precisely because they expose more than a single task’s working files.
Observe a run and grade its artifact
After make doctor reports the relevant configuration checks, the documented local entry point is make dev. Observe which tools are invoked, whether the output is written to the expected task area, and what the final stop reason says. A health response demonstrates service availability, not correct reading, reasoning or artifact creation.
The acceptance fixture below is an editorial exercise, not a native DeerFlow configuration file. A passing report retains both conflicting values with provenance instead of silently choosing one. We have not run this end-to-end assignment; the only executed upstream code in this review consists of isolated standard-library helpers described in the source chapter.
Implementation steps
- 1
Review the pinned checkout and run make check in its supported shell.
- 2
Install dependencies, run make setup and select restrictive capabilities.
- 3
Run make doctor, then make dev in an isolated evaluation environment.
- 4
Compare the resulting artifact with the expected facts and disagreement.
Copy-ready example
{"fixture":{"documentA":{"releaseYear":2024},"documentB":{"releaseYear":2025}},"expected":"cite both documents and mark the year unresolved","externalWritesAllowed":false,"exerciseExecuted":false}Frequently asked questions
Can I paste the make commands into native PowerShell?
The pinned README specifies Git Bash for Windows service scripts; use the documented environment rather than assuming native-shell compatibility.
Must the first task have web search?
No. Supplied, owned documents provide a smaller and more reproducible first evaluation.
Sources
- README.mdSource checked 2026-09-08
- LICENSESource checked 2026-09-08
- backend/README.mdSource checked 2026-09-08
- backend/pyproject.tomlSource checked 2026-09-08
- backend/docs/middleware-execution-flow.mdSource checked 2026-09-08
- backend/packages/harness/deerflow/agents/lead_agent/agent.pySource checked 2026-09-08
- backend/packages/harness/deerflow/agents/middlewares/loop_detection_middleware.pySource checked 2026-09-08
- backend/packages/harness/deerflow/agents/middlewares/_bounded_dict.pySource checked 2026-09-08
- backend/packages/harness/deerflow/config/loop_detection_config.pySource checked 2026-09-08
- backend/packages/harness/deerflow/sandbox/local/local_sandbox_provider.pySource checked 2026-09-08
- backend/app/gateway/auth_middleware.pySource checked 2026-09-08
- backend/app/gateway/csrf_middleware.pySource checked 2026-09-08
- docker/docker-compose.yamlSource checked 2026-09-08