A ByteDance DeerFlow Agentic System

Operations, memory, and run journal for a cloud-hosted autonomous assistant.

---

Overview

Patronus is an autonomous personal assistant built on ByteDance DeerFlow for agent orchestration, Model Context Protocol (MCP) for tool integration, and GitHub Codespaces for safe, cloud-hosted execution. All durable memory, run logs, and mission records live as structured GitHub Issues — providing a transparent, portable, and auditable audit trail.

Repository	Role
8r4n/deerflow-ops ← this repo	Issue-based durable memory, run logs, mission tracking, and bootstrap docs
8r4n/deerflow-skills	Skill implementations — one folder per skill with Dockerfiles, tests, and manifests
bytedance/deer-flow (submodule → deer-flow/)	Upstream DeerFlow runtime for agent orchestration

---

Architecture

Mission issue (deerflow-ops)
  └─► DeerFlow reads mission (via GitHub MCP)
        └─► Creates run log issue (via GitHub MCP)
              └─► Executes in GitHub Codespace
                    ├─► PRs in deerflow-skills
                    ├─► Skill images pushed to ghcr.io
                    ├─► Progress posted to issues (via GitHub MCP)
                    ├─► memory:* issues in deerflow-ops
                    └─► Links everything for traceability

Core components:

Component	Purpose
DeerFlow	Agent orchestration — planner → executor → verifier loop
GitHub MCP	Read/write issues and PRs, search code, update progress, plan missions
Web Fetch MCP	Ingest external documentation and web sources
GitHub Codespaces	Cloud-hosted, ephemeral execution environment
GitHub Container Registry	Versioned skill image publishing (ghcr.io)
GitHub Issues	Durable memory store, audit trail, and programmatic progress interface

See docs/whitepaper.md for the full design rationale.

---

Quick start

Prerequisites

Requirement	Minimum
GitHub account	With Codespaces access
Git	2.x
Python	3.11+
Node.js	18+
Make	any

You also need:

• API keys for at least one LLM provider (OpenAI, Anthropic, etc.) and a search provider (Tavily recommended)
• A GITHUB_TOKEN with repo, write:packages, and codespace scopes

1. Open in GitHub Codespaces (recommended)

Click Code → Codespaces → Create codespace on main in the GitHub UI, or use the CLI:

gh codespace create --repo 8r4n/deerflow-ops --machine standardLinux32gb

The dev container automatically initializes the submodule and installs all dependencies. Configure API keys (step 2), then start services (step 3).

1b. Clone locally

git clone --recurse-submodules https://github.com/8r4n/deerflow-ops.git
cd deerflow-ops

Already cloned without submodules?

git submodule update --init --recursive

2. Configure DeerFlow

cd deer-flow
make config          # generates .env and config.yaml from examples (auto-run in Codespaces)

Edit deer-flow/.env with your API keys:

OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key

Edit deer-flow/config.yaml to select your preferred model(s). See the upstream configuration guide for details.

Codespaces: The aio sandbox (isolated Docker-based code execution) is enabled by default. The sandbox image is pre-pulled during creation. See docs/playbook-phase1-tooling.md for details.

3. Start services

GitHub Codespaces (recommended):

cd deer-flow
make dev                             # starts backend + frontend + nginx

Access the UI via Codespace port-forwarding on port 2026.

Local development:

cd deer-flow
pip install -e ".[dev]" && make dev

4. MCP server reference

Server	Purpose	Authentication
GitHub MCP	Issues, PRs, code search, progress updates	GITHUB_TOKEN (repo, write:packages, codespace)
Web Fetch MCP	Ingest external documentation	None required
Codespaces MCP	Manage Codespace lifecycle	Planned — see Phase 1 roadmap

5. Keep DeerFlow up to date

cd deer-flow && git fetch origin && git checkout main && git pull
cd .. && git add deer-flow && git commit -m "Update deer-flow submodule"

---

Repository structure

deerflow-ops/
├── README.md                        ← you are here
├── extensions_config.json           ← MCP server configuration
├── assets/                          ← project logo and images
├── deer-flow/                       ← bytedance/deer-flow submodule
├── skills/
│   └── _template/                   ← canonical skill skeleton (Phase 2)
│       ├── README.md                ← template documentation
│       ├── Dockerfile               ← container image build
│       ├── skill.yaml               ← skill manifest
│       ├── Makefile                 ← build, test, and GHCR push targets
│       ├── requirements.txt         ← Python dependencies
│       └── tests/                   ← contract test skeleton
├── scripts/
│   └── autonomous_runner.py         ← headless agentic loop (Phase 4)
├── tests/
│   └── test_autonomous_runner.py    ← runner unit tests
├── .devcontainer/
│   └── devcontainer.json            ← GitHub Codespaces dev container
├── docs/
│   ├── whitepaper.md                ← full system design
│   ├── deerflow-software-architecture.md
│   ├── labels.md                    ← GitHub label taxonomy
│   ├── index-issues.md              ← maintaining pinned index issues
│   ├── playbook-phase1-tooling.md   ← Phase 1 tooling playbook
│   ├── playbook-phase2-template-skill.md ← Phase 2 template skill playbook
│   ├── playbook-phase3-autonomous-skill-acquisition.md ← Phase 3 autonomous skill acquisition
│   └── playbook-phase4-agentic-loop.md ← Phase 4 continuous operation
└── .github/
    ├── ISSUE_TEMPLATE/              ← mission, run log, memory templates
    └── workflows/
        ├── ghcr-publish.yml         ← GHCR image push workflow
        └── kickoff.yml              ← automatic mission kickoff

---

Memory model

All durable memory lives as GitHub Issues, organized by label:

Label	Purpose
memory:skill	Skill documentation and metadata
memory:repo	Repository evaluations (adopted / rejected)
memory:playbook	Reusable procedures and setup guides
run:log	Individual execution logs
mission:*	Mission categories (comms, dev, research, …)
status:*	Lifecycle state (active, blocked, done, deprecated)

→ docs/labels.md — full taxonomy
→ docs/index-issues.md — how pinned index issues are maintained

---

Roadmap

Phase	Description	Status
0	Repo bootstrap — templates, docs, labels, indexes	✅ Done
1	Tooling foundation — GitHub MCP, Codespaces, GHCR, web fetch MCP	✅ Done
2	Template skill — canonical _template skeleton with GHCR publish	✅ Done
3	First autonomous skill acquisition run (in Codespaces)	🔜 Next
4	Agentic loop — continuous autonomous operation	✅ Done
5+	Expand mission coverage (planning, research, automation)	🔜 Planned

---

Resources

• 📄 System whitepaper
• 🔄 Agentic loop playbook
• 🛠 DeerFlow Skills repo
• 🔗 ByteDance DeerFlow upstream

---

License

Maintained by @8r4n. The deer-flow/ submodule is licensed under the MIT License by ByteDance.