DeerFlow 2.0은 ByteDance가 공개한 '슈퍼 에이전트 하네스'로, LangGraph 기반 멀티 에이전트 오케스트레이션 위에 샌드박스 실행, 장기 메모리, 스킬/도구, 서브에이전트, 메시지 게이트웨이를 결합해 리서치·코딩·콘텐츠 생성 같은 장시간(수분~수시간) 작업을 자동화합니다. v1(딥리서치 프레임워크)과는 코드 공유 없는 완전 재작성판이며, Slack·Discord·Telegram·Feishu·GitHub 등 다양한 IM 채널과 MCP 서버까지 아우르는 통합 백엔드/프런트엔드 스택입니다.
backend/app/gateway 아래 FastAPI 앱(app.py)이 인증(auth), 스레드/런(run) 관리, 채널 연동, MCP, 스킬, 서브에이전트, 스케줄 태스크 등 라우터들을 등록해 단일 게이트웨이로 노출합니다. 실제 에이전트 로직은 backend/packages/harness/deerflow 패키지가 담당하며 LangGraph 위에서 서브에이전트를 오케스트레이션하고, Docker-out-of-Docker(DooD) 방식으로 샌드박스 컨테이너를 띄워 도구 실행을 격리합니다. .agent/skills 디렉터리는 스킬(예: blocking-io-guard, smoke-test)을 SKILL.md 명세와 스크립트/템플릿으로 정의해 에이전트가 재사용 가능한 SOP처럼 실행하도록 합니다. 확장 기능은 deerflow_extension_api 계약 패키지를 통해 신뢰된 서드파티 파이썬 코드를 설치(cli.py의 install/enable/disable)하는 구조이며, 배포는 Docker Compose(멀티스테이지 Dockerfile: builder/dev/runtime) 또는 make 기반 로컬 실행(uv+pnpm+nginx) 두 경로를 제공합니다.
- STEP 01
저장소를 클론한 뒤 make setup을 실행하면 대화형 위저드가 뜨고 Docker 배포 또는 로컬 개발 중 하나를 선택하게 됩니다.
- STEP 02
config.yaml과 .env가 없으면 스크립트가 자동으로 .env.example을 복사하고 make config로 config.yaml을 생성해주지만, 여기에 LLM 제공자 API 키를 직접 채워 넣어야 다음 단계로 진행됩니다.
- STEP 03
Docker 모드는 check_docker.sh로 Docker 데몬과 2026 포트 점유 여부를 먼저 검사한 뒤 make docker-init, make docker-start로 컨테이너를 띄우고, 로컬 모드는 Node 22+/pnpm/uv/nginx 설치 여부를 check_local_env.sh로 확인한 뒤 make install, make dev-daemon으로 백그라운드 구동합니다.
- STEP 04
서비스가 뜬 뒤 http://localhost:2026 으로 접속하면, 인증이 켜져 있을 경우 /api/models가 401을 반환해 '초기 설정 필요' 상태를 감지하고, /setup 경로에서 최초 관리자 계정을 직접 생성해야 워크스페이스 화면이 열립니다.
- STEP 05
frontend_check.sh 같은 스모크 테스트 스크립트가 회원가입/로그인 API를 호출해 세션 쿠키를 얻고, 이를 이용해 /en/docs 등 보호된 페이지가 정상 렌더링되는지 curl로 확인하는 흐름을 그대로 재현하게 됩니다.
- STEP 06
완전 가동 후에도 90~120초 정도 게이트웨이·프런트엔드·nginx가 안정화될 시간을 기다려야 하며, logs/gateway.log 등 로그 파일로 기동 상태를 지켜봐야 합니다.
성공적으로 띄우면 브라우저에서 워크스페이스 UI를 통해 리서치·코딩·문서 생성 등 멀티스텝 작업을 에이전트에게 위임하고, 그 진행 과정(서브에이전트 호출, 도구 실행, 메모리 반영)을 실시간 스트림으로 관찰할 수 있는 셀프호스팅 슈퍼에이전트 플랫폼을 손에 넣게 됩니다. 추가로 MCP 서버, IM 채널 연동, 스케줄 태스크, 확장 가능한 스킬 시스템까지 같은 백엔드에서 함께 제공됩니다.
LLM API 키(Doubao-Seed-2.0-Code, DeepSeek v3.2, Kimi 2.5 등 권장 모델)를 직접 config.yaml에 넣어야 실제 에이전트가 동작하며, 키 없이는 기동만 되고 작업 수행은 불가능합니다.
샌드박스 모드는 호스트 Docker 소켓을 마운트하는 DooD 구조라서 Docker 실행 환경과 보안 설정(README의 'Improper Deployment May Introduce Security Risks' 경고)을 신경 써야 합니다.
확장(extension) 설치 CLI는 '신뢰된 소스의 코드를 게이트웨이 권한으로 실행'한다고 명시적으로 경고하므로, 서드파티 확장을 설치할 때는 신뢰 여부를 스스로 판단해야 합니다.
최초 부팅 시 관리자 계정을 자동 생성하지 않고 /setup에서 수동 생성하도록 설계되어 있어, 이 단계를 건너뛰면 API가 401만 반환하는 상태로 남습니다.
자체 LLM 인프라와 Docker 환경을 갖춘 팀이 리서치·코딩 자동화를 위한 오픈소스 에이전트 하네스를 셀프호스팅하려 할 때 적합하며, 스킬·서브에이전트·메모리·IM 채널까지 한 번에 통합된 풀스택을 원할수록 가치가 큽니다. Dockerfile 멀티스테이지 구성, FastAPI 라우터 분리, 실제 스모크 테스트 스크립트(인증 흐름 포함), 확장 CLI 코드까지 소스 레벨에서 구조가 구체적이고 일관되게 확인되므로, 직접 설치해보지 않아도 '설정 위저드 → config 채우기 → Docker/로컬 기동 → /setup 관리자 생성 → 워크스페이스 사용'이라는 실제 경험 흐름은 신뢰할 수 있습니다. 다만 API 키 확보, Docker 보안 설정, 확장 신뢰 판단 등 운영자의 추가 판단이 필요한 지점은 README의 보안 공지와 스크립트 경고를 통해 이미 저장소 스스로도 명시하고 있습니다.