The Brain

Open-source workflow orchestrator for developers. Self-hosted, MIT-licensed, runs on your machine. v1.0 released 2026-06-15.

Get it on GitHub   Read the launch post

What it is

A workflow orchestrator with persistent run history. You define a workflow as a Python file — a sequence of named steps. The Brain runs it on whichever of the four triggers you registered, persists every step's result to a single Postgres database, and stops on the first failure with a clear error. brain history shows what ran. brain show <run-id> shows the per-step detail. brain diagnose produces a redacted zip ready to attach to a bug report.

It runs entirely on your machine. No SaaS account. No telemetry. No cloud lock-in. docker compose --profile api up -d and it's running.

The biggest thing about The Brain is what it deliberately doesn't do: it doesn't decide anything on its own. Workflows are scripted Python. The LLM step transforms text. The workflow file is the agent; The Brain is the runtime that runs it.

What v1.0 does

• Four step types — ShellStep runs subprocess commands; LLMStep calls an OpenAI-compatible chat API with per-step provider/model/key overrides; MemoryVaultStep calls Memory Vault's REST API; McpToolStep calls any MCP tool over stdio.
• Four trigger types — manual (CLI), cron (scheduler daemon), webhook (HMAC-verified HTTP POST), file (debounced filesystem watcher).
• Substitution between steps — {previous.step-name} references prior step output; {trigger.body} / {trigger.path} reference trigger payload data.
• Three processes, one database — CLI for one-shot runs, brain serve for the HTTP API + webhook intake, brain watch for cron and file triggers. Compose profiles let you run any subset.
• Structured logging with run_id binding — every log line emitted inside a run carries the run UUID as a structured field. JSON or human-readable, switchable via LOG_FORMAT.
• Redacted diagnostic bundle — brain diagnose writes a timestamped zip with logs, environment, OS info, Brain version. Sensitive env vars are recorded as presence-only — name appears, value never appears.
• Multi-arch Docker — linux/amd64 and linux/arm64 images at ghcr.io/mihaibuilds/the-brain.
• 363 tests passing — pytest with a real Postgres service container in CI, no mocks at integration boundaries.

Quick start

docker pull ghcr.io/mihaibuilds/the-brain:latest

git clone https://github.com/MihaiBuilds/the-brain
cd the-brain
cp .env.example .env
docker compose --profile api up -d

Open http://localhost:8001 for the HTTP API. Run brain run examples/hello.py from the CLI.

Architecture

One Postgres database for run history, webhook secrets, and scheduler state — no Redis, no queue. Three processes (CLI, HTTP API daemon, watcher daemon) share that database; Compose profiles let you run any subset. Per-step subprocess spawn for shell and MCP steps means a crashing step never takes the runner down. Workflows are trusted Python files, not a YAML DSL — full editor support, full type checking, the workflow file is part of your trust boundary. The full architectural decisions are in the v1.0 launch post and the ARCHITECTURE.md in the repo.

Ecosystem composition

Memory Vault is the substrate that stores and retrieves. The Brain is the engine that runs workflows. Both run independently; both compose together via the derive-pattern — you write a Dockerfile that derives FROM ghcr.io/mihaibuilds/the-brain:1.0 and installs the MCP servers you want available, and the workflow's McpToolStep spawns them as per-step subprocesses. The same shape works for Memory Vault's MCP server, GitHub's, Sentry's, or your own. The Brain ships zero MCP servers in the stock image — composition is opt-in and explicit.

Honest limitations

• No retries on step failure — first failure halts the workflow. The persisted run row shows where and why. Retry policy is a v1.x candidate.
• No catch-up on missed cron windows — if The Brain is down when a cron expression matches, that window is skipped, not deferred.
• No tools/list discovery for MCP servers — workflow authors know the tool name and argument shape in advance.
• No MCP over HTTP transport — stdio only in v1.0.
• No LLM-driven tool orchestration — LLMStep is chat-completion only. If a workflow wants "LLM picks the next tool," the workflow wires that explicitly.
• No bundled MCP servers in the stock image — derive-your-own-image is the documented path.
• Single-tenant — multi-user with workspace isolation is part of the planned PRO tier.
• No visual workflow builder — workflows are Python.

Honest gaps documented up front build more trust than feature bullets that fall apart when someone actually tries them.

Open-core model

The Brain is and will always be MIT-licensed. The free tier — the runner, all four step types, all four trigger types, the HTTP API, the CLI, the scheduler and watcher daemons, structured logging, the diagnose bundle, the multi-arch Docker images — is the full runtime, not a crippled demo. A paid PRO tier is planned for teams: multi-user with workspace isolation, a hosted scheduler, a secrets vault, conflict resolution for shared workflow repos, additional integrations. v1.x stays free forever. Open-core, not bait-and-switch.

Build journey

The Brain was built in public over five weeks across five locked milestones, starting May 18 2026. Each milestone shipped with a blog post explaining the technical decisions and trade-offs:

• M1 — I Built the Memory, Now I'm Building the Brain (2026-05-27)
• M2 — The Brain Runs on a Schedule Now (2026-06-04)
• M3 — The Brain Reacts Now (2026-06-07)
• M4 — The Brain Talks to Everything Now (2026-06-11)
• M5 — v1.0 Released (2026-06-15)

Try it

• Repo
• Latest release
• README and quick start
• ARCHITECTURE.md — the design overview
• SECURITY.md — threat model and workflow-input trust posture
• Questions and bug reports: GitHub Issues
• General discussion: GitHub Discussions
• Follow along: @mihaibuilds on X, blog

→ Read the full v1.0 launch writeup