OpenFlowsOpenFlows
- Get Started
- Get Started

Installation

OpenFlows is a thin orchestration brain that runs on top of a self-hosted Coder deployment. 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.

The only supported installation path is Docker Compose. It brings up the entire stack - Coder, Redis, and the OpenFlows engine - with consistent networking and a single configuration surface. Other legacy methods (npm, one-liner scripts, and cargo install) are no longer supported and have been removed from the documentation.

Prerequisites

Token scopes

For a complete breakdown of GitHub OAuth scopes, Coder external auth configuration, and the minimum viable credential setup, see the Token Guide.

Docker Compose Stack

Clone the repository, copy the environment template, and start the stack:

bash
git clone https://github.com/The-AgenticFlow/openflows.git
cd openflows
cp .env.example .env   # edit with your GitHub OAuth app credentials

# Start the infrastructure stack
docker compose up -d

What this starts

  • Coder - governed execution environment on port 7080
  • Redis - SharedStore for agent coordination on port 6379
  • OpenFlows engine - orchestration layer and NEXUS reconcile loop
  • All services wired together with internal Docker networking

Bootstrap OpenFlows

After the infrastructure is healthy, run the bootstrap command. It creates the OpenFlows admin user, pushes Coder templates for each role (nexus, forge, sentinel, vessel, lore), and verifies that the orchestration layer can reach Coder and Redis.

bash
./scripts/prod.sh bootstrap

If bootstrap fails, the CLI prints a specific diagnostic and exits non-zero. Common causes are missing GitHub OAuth credentials, an unreachable Coder server, or a Redis connection failure. See Troubleshooting for resolution steps.

Run the Controller

Start the Orchestrator. This command always resets Redis to a clean slate before starting the controller. It runs in the foreground - keep this terminal open or run it in a service manager.

bash
./scripts/prod.sh run

Monitor the controller logs in another terminal:

bash
tail -f /tmp/openflows-controller.log

Add Your First Tenant

A tenant represents a team bound to a specific repository. The tenant add command creates a Coder user for the team, links the repository through Coder external auth, and provisions the openflows-nexus workspace that polls the repo for issues.

bash
./scripts/prod.sh tenant owner/repo --name my-team

The first time a tenant is added, the owning user must complete the Coder external-auth flow to grant GitHub access. After that, NEXUS can clone, create branches, open PRs, and merge on behalf of the tenant. Tenant state is isolated by Redis keyspace prefixes (ns:{tenant}:...).

Health Check

Verify the full stack is functional:

bash
./scripts/prod.sh doctor

Create Your First Issue

With the tenant active, create a GitHub issue in the bound repository. NEXUS detects it on the next poll cycle, assigns it to an available FORGE worker, and the autonomous cycle begins. No further CLI commands are required for normal operation.

bash
# Create a GitHub issue in owner/repo  -  OpenFlows picks it up automatically

Environment Configuration

The .env.example file contains every required and optional variable. Copy it to .env and edit at minimum:

GitHub OAuth App

Required for Coder external authentication. Create a GitHub OAuth App and add the client ID and secret to your .env file.

LLM Provider

Configure at least one model in the Coder dashboard (AI Settings → Coder Agents → Models). OpenFlows routes all LLM calls through the Coder AI Gateway.

Multi-Tenancy

Each team is a tenant with its own repository binding. The tenant add command links a GitHub repository to an OpenFlows team.

Coder Templates

Bootstrap pushes the openflows-{role} templates to your Coder deployment for ephemeral workspace provisioning.

Architecture-first approach

OpenFlows encodes architectural discipline through:
  • PocketFlow engine - declared flow graph for agent coordination
  • SharedStore contracts - typed Redis schemas for state management
  • Node trait pattern - prep → exec → post separation for each agent
  • Explicit routing table - recovery built into every step

Verification

After running docker compose up -d, verify all services are running:

bash
# Check Docker containers
docker ps

# Expected output should show:
# - coder (port 7080)
# - redis (port 6379)
# - openflows engine

Development Workflow

For operators and contributors iterating on OpenFlows itself, rebuild and redeploy binaries after code changes:

bash
# After code changes, rebuild and update binaries
./update-binaries.sh

Next steps

After installation and tenant setup:
  1. OpenFlows automatically monitors the bound repository for issues.
  2. Create a GitHub issue to trigger the autonomous team.
  3. Watch NEXUS pick it up, FORGE write code, SENTINEL review, and VESSEL ship the PR.
  4. LORE documents the changes automatically.
See the Getting Started guide for the full walkthrough and the First Issue Walkthrough for a step-by-step example.
🔑
Token Guide
GitHub OAuth scopes and Coder external auth setup.
🏢
Multi-Tenancy
Tenant model, Redis namespacing, and team isolation.
🔧
Troubleshooting
Common bootstrap and runtime failures.
🏗️
System Design
PocketFlow, SharedStore, and NEXUS reconcile.