OpenFlowsOpenFlows
- Get Started
- Get Started

Quick Start Guide

Getting Started

OpenFlows is a thin orchestration layer that runs on top of a self-hosted Coder deployment. It turns a declared PocketFlow graph, typed Redis SharedStore contracts, and a reconcile loop into an autonomous engineering team: issue detection, planning, implementation, adversarial review, CI verification, and merge - all driven by NEXUS and executed by ephemeral Coder workspaces. No AI software, no LLM keys, and no GitHub tokens live inside a worker workspace.

~10 min read 4 steps Beginner

Why architecture-first

AI can generate code against a spec, but it cannot write the spec. As models make boilerplate cheap, the real difficulty shifts upward - into architectural thinking, typed contracts, and security-aware execution. OpenFlows encodes that discipline: a declared PocketFlow graph, typed SharedStore state contracts, an explicit routing table, and recovery built into every step. Engineering goes in; software comes out.

1Prerequisites

Docker 24+
Required for running the Docker Compose stack with Coder, Redis, and OpenFlows.
Get Docker
Git 2.x+
Required for cloning repositories and version control operations.
Get Git
GitHub OAuth App
Required for Coder external authentication. Create a GitHub OAuth App for your organization.
Create OAuth App
LLM Provider
At least one model configured in the Coder dashboard (AI Settings → Coder Agents → Models).

Coder governs where agents run; OpenFlows governs how they coordinate

The integration is deliberate and asymmetrical:
  • Coder is the only runtime. It provides ephemeral workspaces, control-plane AI agents, model governance, identity, audit logging, and cost tracking. Worker workspaces contain zero AI software, zero LLM keys, and zero GitHub tokens.
  • OpenFlows is the orchestration brain. It provides the PocketFlow graph, typed SharedStore contracts, the NEXUS reconcile loop, and the FORGE↔SENTINEL planning cycle.
Coder Agents run in the control plane, not in workspaces. They invoke tools by connecting to workspaces over the same secure tunnel used by IDEs.

2Quick Start Installation

The only supported path is Docker Compose. Clone the repository, copy the environment template, start the stack, bootstrap OpenFlows, and add your first tenant. The entire sequence takes a few minutes.

bash
git clone https://github.com/The-AgenticFlow/openflows.git
cd openflows
cp .env.example .env   # Edit .env: set GITHUB_TOKEN but leave CODER_SESSION_TOKEN empty

# 1. One-time Bootstrap (creates admin user, pushes templates, verifies LLM/GitHub auth)
./scripts/prod.sh bootstrap

# 2. Start the Controller (resets Redis, starts controller)
./scripts/prod.sh run

# 3. Add a tenant (links GitHub repo, creates nexus workspace)
./scripts/prod.sh tenant owner/repo --name my-team

# 4. Create a GitHub issue  -  OpenFlows picks it up automatically

Production Architecture

In production, the controller runs inside a Nexus workspace provisioned by Coder. The workspace auto-starts the controller via its startup_script.

text
Coder provisions nexus workspace from template
    ↓
Workspace startup script runs
    ↓
Line 1: Installs openflows-harness binary
    ↓
Line 2: Starts heartbeat daemon
    ↓
Line 3: Executes: openflows run
    ↓
Controller auto-starts inside workspace

The nexus workspace template is in crates/coder-client/templates/openflows-nexus/. It receives all env vars from Coder and auto-starts the controller.

The openflows-harness CLI

Each worker workspace receives a small openflows-harness binary. The Coder Agent invokes it via shell (guided by skills) to read and write the Redis SharedStore with typed, validated schemas. Agents never run redis-cli directly - the harness is the only Redis client inside a workspace.

See the Installation Guide for a detailed configuration reference, the Token Guide for GitHub and Coder auth scopes, and the First Issue Walkthrough for a complete end-to-end example.

3Multi-Tenancy Model

One Coder server serves many teams. Each tenant is a real Coder user, a repository binding, and an openflows-nexus workspace. Tenants are isolated by Coder RBAC and by per-tenant Redis keyspace prefixes (ns:{tenant}:...).

bash
# Add another tenant
./scripts/prod.sh tenant another-org/another-repo --name team-b

Environment Configuration

Copy .env.example to .env and configure:
  • GitHub OAuth App credentials for Coder external auth
  • Coder deployment settings
  • LLM provider settings in the Coder dashboard
The bootstrap process handles template deployment and initial validation. For a full reference, see Multi-Tenancy.

3.1 Plug-and-Play Extension

OpenFlows is designed for extension without modifying core orchestration code:

Add a skill

Drop a directory into orchestration/plugin/skills/ with a SKILL.md, list it in orchestration/agent/registry.json under the role's skills array, and run ./update-binaries.sh. No Rust code change is required.

Add an MCP server

Add it to the role's mcp object in registry.json, or register it centrally in the Coder dashboard (AI Settings → MCP Servers). Both coexist.

Enable a new model

Configure it in the Coder dashboard (AI Settings → Coder Agents → Models), then reference it in orchestration/agent/registry.json via the model field. See Model Routing.

Development updates

After code changes, run ./update-binaries.sh to rebuild and redeploy binaries to all workspaces.

How it works

OpenFlows runs a team of AI agents that collaborate like a real engineering team: 
You create a GitHub issue → NEXUS picks it up → FORGE writes code → SENTINEL reviews adversarially
→ VESSEL merges green PRs → LORE documents → you get a merged PR
You are escalated only for security concerns, ambiguous specifications, or major architectural decisions.

4Create Your First Issue

Once OpenFlows is running and your tenant is configured, create a GitHub issue in your repository. OpenFlows will automatically:

  1. NEXUS detects the issue on its next poll cycle.
  2. FORGE is assigned the ticket with a unique identifier.
  3. An ephemeral Coder workspace is provisioned for the FORGE worker.
  4. FORGE writes code against the agreed contract.
  5. SENTINEL reviews every segment adversarially.
  6. VESSEL handles CI, conflicts, and merge.
  7. LORE documents the changes automatically.
  8. The workspace is torn down after merge - no lingering state.

The team

Agent Role What it does
NEXUS Orchestrator / Controller Assigns issues, coordinates the team, owns recovery, and notifies you when needed.
FORGE Builder Writes code against an agreed contract, creates branches, and opens PRs.
SENTINEL Reviewer Adversarially reviews code for security, quality, and test coverage.
VESSEL DevOps Monitors CI, handles merge conflicts, and squash-merges green PRs.
LORE Writer Documents decisions, updates changelogs, and maintains project history.

5Next Steps

🔑
Token Guide
GitHub OAuth scopes, Coder external auth, and the minimum viable credential setup.
🎯
First Issue Walkthrough
Step through a complete ticket from issue creation to merged PR.
🏗️
System Design
PocketFlow, SharedStore contracts, and the NEXUS reconcile loop.
👥
Agent Roles
Contracts, permissions, workspace lifecycle, and CLI modules for each role.
❓
FAQ
Short answers to common setup, security, and operational questions.

Documentation

Was this guide helpful?