github/deer-flow
1
0
Fork 0
mirror of https://github.com/bytedance/deer-flow.git synced 2026-08-10 14:58:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
deer-flow/AGENTS.md
Nan Gao 2a143dced6
fix(docker): bind the published entry port to loopback by default (#4618) 
README documents DeerFlow as deployed by default "in a local trusted
environment (accessible only via the 127.0.0.1 loopback interface)", but both
compose files published nginx as `"${PORT:-2026}:2026"`, which Docker binds to
0.0.0.0 and [::]. The shipped artifact did not match its own documented
default, so running it on a LAN or cloud host produced a wider surface than
the docs implied without the operator changing anything -- and the agent can
execute commands.

Publish as `"${BIND_HOST:-127.0.0.1}:${PORT:-2026}:2026"` in both compose
files, so the default matches the documented model while operators who front
the stack with their own TLS/auth can still widen it via BIND_HOST. The
Gateway keeps binding 0.0.0.0:8001 inside the container (nginx reaches it over
the compose network) and its port stays unpublished, so the published nginx
port is the entire external surface.

BREAKING CHANGE: a deployment that relied on the previous 0.0.0.0 default
becomes unreachable from other hosts after this upgrade. Set BIND_HOST=0.0.0.0
in .env to restore it, after putting authentication in front and completing
first-run setup.

Also:
- .env.example documents BIND_HOST and PORT with the reasoning.
- deploy.sh reports the address the stack actually bound and, when it is not
  loopback, tells the operator to complete first-run setup immediately. It
  reads BIND_HOST/PORT from .env via a new read_dotenv_value helper following
  compose precedence; the shell does not source .env, so reading the
  environment alone would have reported "loopback only" for a stack .env had
  exposed. The pre-existing ${PORT} summary line had the same defect and is
  fixed with it.
- test_compose_default_bind_host.py pins the loopback default, that BIND_HOST
  stays overridable, and that no service in either compose file publishes a
  port without an explicit bind address, so a later addition cannot drift back
  to 0.0.0.0 unnoticed.
2026-08-01 08:35:02 +08:00

9.0 KiB
Raw Blame History

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, and others) when working with code in this repository. It is the source of truth; the sibling CLAUDE.md imports it via @AGENTS.md.

It is the monorepo orientation layer: it maps the whole repo and points to the module guides that own the depth. For anything inside a module, read that module's guide rather than expecting full detail here:

  • backend/AGENTS.md — backend depth: harness/app split, agent & middleware chain, sandbox, MCP, skills, memory, IM channels, persistence/migrations, config system, test layout.
  • frontend/AGENTS.md — frontend depth: Next.js App Router layout, thread/streaming data flow, code style, commands.

What is DeerFlow

DeerFlow is a LangGraph-based AI super-agent system with a full-stack architecture. The backend runs a "super agent" with sandboxed execution, persistent memory, subagent delegation, and extensible tools (built-in, MCP, community), all per-thread isolated. The frontend is a Next.js chat UI. External IM platforms (Feishu, Slack, Telegram, Discord, DingTalk) bridge into the same agent through the Gateway.

Service Topology

A single make dev / Docker stack runs four cooperating services:

Service Port Role
Nginx 2026 Unified reverse-proxy entry point — open this in the browser
Gateway API 8001 FastAPI REST API + embedded LangGraph-compatible agent runtime
Frontend 3000 Next.js web interface
Provisioner 8002 Optional — only when sandbox is configured for provisioner/K8s mode

Nginx is the single public entry: it serves the frontend and proxies /api/langgraph/* to the Gateway's LangGraph runtime, rewriting it to Gateway's native /api/* routes; all other /api/* go straight to the Gateway REST routers. See backend/AGENTS.md for the runtime and router detail.

Both compose files publish that entry as "${BIND_HOST:-127.0.0.1}:${PORT:-2026}:2026" — loopback by default, matching the README's documented deployment model. A bare "${PORT}:2026" binds 0.0.0.0, which does not. Nginx itself listens default_server on IPv4+IPv6 and the Gateway binds 0.0.0.0:8001 inside the container on purpose — both are container- internal; the published nginx port is the entire external surface, and the Gateway's 8001 is deliberately not published. Any new published port needs an explicit bind address; backend/tests/test_compose_default_bind_host.py pins this for every service in both compose files.

Repository Map

deer-flow/
├── Makefile                        # Root orchestration: drives the full stack (dev/start/stop, docker, setup)
├── config.example.yaml             # Template → copy to config.yaml (gitignored) at repo root
├── extensions_config.example.json  # Template → copy to extensions_config.json (gitignored): MCP servers + skills
├── backend/                        # Python backend — see backend/AGENTS.md
│   ├── Makefile                    # Per-module backend commands (dev, gateway, test, lint, migrate-rev)
│   ├── packages/harness/           # deerflow-harness package (import: deerflow.*) — agent framework
│   └── app/                        # FastAPI Gateway + IM channels (import: app.*)
├── frontend/                       # Next.js frontend (pnpm) — see frontend/AGENTS.md
├── docker/                         # docker-compose files, nginx config, provisioner
├── skills/                         # Agent skills: public/ (committed), custom/ (gitignored)
│                                    # Managed integration skill packs are global at .deer-flow/integrations/skills/{provider}/
│                                    # Integration credentials and enabled state remain per-user
├── contracts/                      # Cross-component JSON contracts (e.g. subagent status, skill review)
├── scripts/                        # Root orchestration scripts invoked by the Makefile (check, configure, doctor, support_bundle, serve, nginx, docker, deploy, setup_wizard)
├── tests/                          # Root-level tests (currently tests/skills/ — public skill tests)
└── docs/                           # Cross-cutting docs, plans, and design notes

Runtime config lives at the repo root: copy config.example.yaml → config.yaml (main app config) and extensions_config.example.json → extensions_config.json (MCP servers + skills). Both real files are gitignored and may be edited at runtime via the Gateway API. Config schema and resolution order are documented in backend/AGENTS.md.

Skill quality review note:

  • skills/public/skill-reviewer/ is the built-in read-only skill quality reviewer. It uses the harness-layer review_skill_package tool and contracts in contracts/skill_review/. Model-visible review data is compact and tag-neutralized; full raw payloads stay in tool artifacts. See backend/AGENTS.md for the non-activation, SkillScan, and skill-creator ownership boundaries.

Scheduled-task note:

  • The scheduled-task MVP adds a workspace page at /workspace/scheduled-tasks plus a background scheduler service gated by config.yaml -> scheduler.enabled.
  • Scheduled background runs are intentionally non-interactive: they execute through the normal run lifecycle, but the lead-agent toolset excludes ask_clarification when context.non_interactive=true. The key is honored only for internally-authenticated callers (the scheduler launch path); client-supplied context.non_interactive is dropped.

Commands: Root vs. Module

Root make targets drive the whole stack (run from the repo root):

make setup       # Interactive setup wizard (recommended for new users)
make doctor      # Check configuration and system requirements
make support-bundle  # Generate redacted troubleshooting summary, AI issue draft, and optional zip
make config      # Generate local config files from the examples
make check       # Check that required tools are installed
make install     # Install all dependencies (frontend + backend + pre-commit hooks)
make dev         # Start all services with hot-reload (Gateway + Frontend + Nginx)
make start       # Start all services in production mode (local, optimized)
make stop        # Stop all running services
make up / down   # Build/stop the production Docker stack (browser at localhost:2026)
make docker-start / docker-stop / docker-logs   # Docker development environment

Run make help for the full list.

Per-module commands drive a single module (run inside that module):

# Backend (see backend/AGENTS.md for the full set)
cd backend && make dev        # Gateway API with reload (port 8001)
cd backend && make test       # Backend test suite
cd backend && make lint       # ruff check
cd backend && make format     # ruff format

# Frontend (see frontend/AGENTS.md for the full set)
cd frontend && pnpm dev       # Dev server with Turbopack (port 3000)
cd frontend && pnpm check     # Lint + type check (run before committing)
cd frontend && pnpm test      # Unit tests

Rule of thumb: root make = the full application; backend/Makefile and frontend/ (pnpm) = per-module work.

Host-side pnpm consumers, including the root/frontend Makefiles and local diagnostic scripts, must run through scripts/pnpm.py. The runner preserves direct pnpm/pnpm.cmd priority, falls back to corepack pnpm, and is invoked from frontend/ so Corepack honors the package-manager version pinned by that project.

Where to Go Next

Cross-Cutting Conventions

These apply repo-wide; module guides own the module-specific detail.

  • Documentation update policy — keep docs in sync with code: update README.md for user-facing changes and the relevant AGENTS.md for development/architecture changes in the same change set.
  • Test-driven development — features and bug fixes ship with tests. Backend tests live in backend/tests/ (TDD is mandatory there; see backend/AGENTS.md); frontend tests live in frontend/tests/.
  • Format before pushing — run make format (backend) / pnpm check (frontend). Backend CI enforces ruff format --check, so formatting must be clean before a push.