Frequently Asked Questions

OpenFlows is a thin orchestration brain that runs on top of a self-hosted Coder deployment. Coder is the only runtime. OpenFlows provides the PocketFlow graph, typed Redis SharedStore contracts, and the NEXUS reconcile loop; Coder 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 routes all LLM calls through the Coder AI Gateway, which natively supports Anthropic, OpenAI, Google, and Bedrock. Any OpenAI-compatible endpoint (Fireworks, Groq, Together, etc.) also works through the Gateway. Each agent can use a different provider and model, configured in orchestration/agent/registry.json. For air-gapped or self-hosted deployments, point the Coder AI Gateway at local or self-hosted models. API keys are managed centrally by the Gateway and never exposed inside workspaces.

The Coder AI Gateway is the primary LLM route. It manages API keys centrally - keys never enter workspaces. When an agent makes an LLM call, it goes through the Gateway, which handles authentication, rate limiting, usage tracking, and cost attribution per user. OpenFlows does not maintain a separate LiteLLM fallback; all routing is configured in Coder.

Coder Agents run in the Coder control plane, not inside workspaces. OpenFlows uses the Coder Chats API to ask a control-plane agent to perform work, and the agent connects to the worker workspace over the same secure tunnel used by IDEs. This keeps LLM keys, model access, and long-lived credentials out of the workspace.

Yes. GitHub identity is handled by Coder external auth - configure a GitHub external auth provider in your Coder deployment and include the git-config module in your workspace templates. Each tenant then acts under its logged-in Coder user's GitHub identity. No personal access tokens are stored in OpenFlows or inside workspaces.

Yes. Coder runs in a VPC, on-prem, or fully air-gapped environment. Configure the Coder AI Gateway to point to self-hosted or local model endpoints. No data leaves your infrastructure. Coder provides full audit logging and SSO integration for enterprise compliance.

SENTINEL evaluates against five criteria on every segment: correctness, security vulnerabilities, test coverage, standards compliance, and no regressions. It writes segment-N-eval.md after each FORGE commit and final-review.md at the end. SENTINEL runs in its own ephemeral Coder workspace, spawned fresh per evaluation, so it has no accumulated bias. It is read-only and cannot modify code.

FORGE writes a STATUS.json with status: "BLOCKED" and a specific, answerable question. NEXUS detects this on the next cycle and can re-assign the ticket or escalate. If a worker times out (default 30 minutes), the ticket is marked failed and retried up to three times before being marked exhausted. The ephemeral Coder workspace is torn down on failure - no lingering state.

OpenFlows itself is MIT licensed and free to run. The cost is LLM API usage, tracked by the Coder AI Gateway with per-user and per-group spend controls. A typical full cycle (NEXUS + FORGE + SENTINEL + VESSEL + LORE) uses roughly 50,000-150,000 tokens depending on task complexity. Per-agent model routing via registry.json lets you optimize cost per role.

Yes. Set "instances": 4 for FORGE in registry.json to provision forge-1 through forge-4 running in parallel. Each gets its own isolated ephemeral Coder workspace with its own Git worktree and branch. NEXUS automatically distributes tickets across idle workers.

Code context is sent only to the LLM provider you configure in registry.json, routed through the Coder AI Gateway. OpenFlows itself does not send code to any third-party service. For maximum privacy, run Coder air-gapped with the AI Gateway pointing to a self-hosted or local model - no data leaves your infrastructure.

VESSEL detects conflicts early via GitHub's mergeable field before CI completes. It attempts automated resolution via GitHub's update-branch API or a local rebase inside the Coder workspace. If it cannot resolve automatically, it writes CONFLICT_RESOLUTION.md with context and re-routes the ticket back to the same FORGE worker - no new branch, no context loss.

Each FORGE worker runs inside an ephemeral Coder workspace that is provisioned when NEXUS assigns a ticket and torn down after the PR is merged. This means no lingering state, no stale credentials, and no disk bloat. If a task fails or times out, the workspace is also torn down. The next ticket gets a fresh workspace with the latest template and harness - a clean slate every time.

The SharedStore is a typed Redis state layer that every agent reads and writes through the openflows-harness CLI. It uses validated schemas for tickets, plans, segment evaluations, CI status, and final reviews. By centralizing state in Redis rather than passing free-form messages between agents, OpenFlows guarantees that every role sees a consistent, strongly typed view of the ticket.

NEXUS is the controller. It polls the SharedStore and GitHub on a regular cadence, compares the observed state to the desired state, and takes action: retry a failed worker, reassign a blocked ticket, or escalate to a human. Recovery is built into the flow graph, not bolted on as an afterthought. Every worker writes a STATUS.json so NEXUS can reason about progress without guessing.

Run ./update-binaries.sh from the repository root. It rebuilds the Rust binaries and pushes fresh harness and orchestration artifacts to all Coder workspaces. For registry-only changes (skills, models, MCP servers), updating orchestration/agent/registry.json and running ./update-binaries.sh is usually sufficient. See the Operations guide for the full workflow.

Drop a skill 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. To add a model, configure it in the Coder dashboard and reference it in registry.json via the model field.

OpenFlows control-plane endpoints are documented in the API Reference. The primary integration surface for most users is the CLI (bootstrap, tenant) and the orchestration/agent/registry.json v2 configuration file.

Start with the Troubleshooting guide. It covers bootstrap failures, Coder connectivity, Redis issues, stuck tickets, merge conflicts, and the STATUS.json protocol. If you cannot resolve the issue, open a discussion on the OpenFlows GitHub repository.