> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime

> Brain is built on the deer-flow harness. Why, and what it gives us.

# Runtime

Brain runs on top of the **deer-flow** harness — an open-source platform that
combines a FastAPI gateway, a LangGraph-compatible agent runtime, sandboxed
execution, a Next.js web UI, and built-in tracing.

We chose deer-flow as the runtime instead of building directly on Claude Agent SDK
or LangGraph because it gives us most of the platform plumbing out of the box, and
internal ops at VinMake needs that plumbing on day one.

## What deer-flow provides

* **Multi-user, multi-thread.** Mai and Zean each have their own threads, sessions,
  and history. We don't have to build user isolation from scratch.
* **Next.js web UI.** A working frontend with auth, navigation, chat, and file
  upload. Customizable.
* **FastAPI gateway.** REST and WebSocket entry points with JWT and CSRF validation.
* **LangGraph-compatible runtime.** All our Tier 2 workflows can use LangGraph
  patterns directly. LangGraph Studio works against the same runtime.
* **Sandboxed file and command execution.** Useful for tools that need to process
  uploads or run scripts.
* **Tracing hooks.** LangSmith, Langfuse, and Laminar are all wired in. We pick
  which to activate (see [Observability](/brain/staging/architecture/observability)).
* **Skills, tools, memory, uploads, artifacts.** Standard primitives for agent
  development.

## What it doesn't replace

* Brain's **product logic**: the workflows, prompts, templates, integration with
  CutMake, the correction loop, the role/permission model, the UI surfaces (Inbox /
  Ask / Task / Engine). All of that is ours to build.
* Brain's **data model**: the drafts, tasks, approvals, and correction logs live in
  Brain's own Supabase project.

## Why not Claude Agent SDK directly

The SDK is excellent for building agents but doesn't ship with a UI, multi-user
session management, gateway authentication, or a runtime that other people on the
team can debug visually. We'd build a lot of platform code before we could ship
a single workflow that Mai could use.

## Why not LangGraph alone

LangGraph is the orchestration engine. It doesn't ship with a UI, gateway, or
multi-user runtime either. deer-flow gives us LangGraph **plus** the surrounding
platform, and we keep full LangGraph compatibility for our workflows.

## The cost: we're maintaining a fork

deer-flow is an open-source project we're forking. Every upstream change becomes a
merge problem the more we customize. The discipline that keeps this manageable:

* **Customizations live as skills, tools, and configs** — not patches to the harness
  internals.
* **Brain's product logic is in its own packages**, not interleaved with deer-flow
  source.
* **Forks of harness internals are last-resort.** When we do need to modify the
  harness (e.g., for tracing config, auth integration), the changes are minimal,
  focused, and documented.

This keeps upstream merges cheap and Brain's codebase clean.

## What ships in the deer-flow fork

The fork is private to VinMake (`vinmaketeam/agent-research`). Visible changes from
upstream:

* Brand and visible UI scrubbed to "Agent Workspace"
* LangGraph Studio compatibility for our auth model
* Tracing configuration for LangSmith / Langfuse / Laminar
* Brain's skills, tools, workflows, and agents (added; not replacements)

## Related

* [Implementation Tiers](/brain/staging/architecture/tiers) — what runs on this
  runtime
* [Observability](/brain/staging/architecture/observability) — tracing
  configuration on top of the runtime
* [Data Integration](/brain/staging/architecture/data-integration) — where Brain
  stores its own state vs. reading CutMake