Coder Integration

OpenFlows is a thin orchestration brain that runs on top of a self-hosted Coder deployment. Coder is the runtime. OpenFlows does not provision virtual machines, manage SSH keys, host models, or maintain a user directory. It tells Coder to create a workspace, binds a worker to it, and then coordinates the agents through the Coder API. When the ticket is done, it tells Coder to destroy the workspace. Everything that is hard about infrastructure - identity, isolation, audit, cost tracking, and model governance - is delegated to Coder.

This split is intentional. Coder is a mature, self-hosted platform for development environments. It already knows how to provision ephemeral workspaces, enforce SSO, route LLM calls through a central gateway, and log every action. OpenFlows adds the layer that turns those capabilities into an autonomous engineering pipeline: a directed flow graph, a typed state store, adversarial review, and crash recovery. The two layers are complementary, not competitive.

What Coder Provides

Coder is responsible for the runtime substrate. A single Coder deployment can serve many OpenFlows tenants, and each tenant benefits from Coder's built-in controls without OpenFlows reimplementing them.

OpenFlows as a Thin Orchestration Brain

If Coder is the body - the workspaces, the network, the identity, the model gateway - OpenFlows is the nervous system. It decides which agent should act on which ticket, in what order, with what review gates, and with what recovery behaviour. It does this by maintaining the SharedStore and driving the PocketFlow graph.

The orchestrator is a Rust process that runs somewhere with network access to Coder and Redis. It does not need a large GPU or a model server. It only needs to call the Coder API, the GitHub API (via Coder external auth), and Redis. All LLM calls are forwarded to the Coder AI Gateway, which owns the keys and the model configuration. The orchestrator never sees an API key.

{
  "workspace_provider": "coder",
  "coder_module": "claude-code",
  "ai_gateway": {
    "primary": "coder",
    "fallback": "litellm"
  }
}

Control-Plane AI Agents vs Workspace Agents

Coder has two ways of using AI agents, and the distinction is important for understanding OpenFlows.

Control-plane AI agents run in the Coder control plane and are exposed through APIs. They are centrally managed, can see all workspaces, and are governed by the Coder AI Gateway. They are ideal for orchestration: long-running tasks, routing decisions, and multi-workspace coordination.

Workspace agents run inside an individual Coder workspace, usually attached to the editor or IDE. They have local context, can edit files in that workspace, and are tied to the user's chat session. They are ideal for interactive coding assistance, not for autonomous, cross-workflow orchestration.

OpenFlows uses the control-plane model for orchestration. NEXUS, FORGE, and SENTINEL are not sitting in a chat window inside a workspace; they are worker identities that the orchestrator dispatches to Coder workspaces. The coder_module field in registry.json determines which CLI tool (Claude Code, Codex, Aider) is installed inside the workspace for the agent to use.

Chats API vs AgentAPI

Coder exposes two APIs for agent interaction. OpenFlows uses the Chats API for orchestration. The AgentAPI is the in-workspace API used by editor-embedded agents.

Complementary Layers

The cleanest way to think about the architecture is as a stack of responsibilities. Coder owns the bottom two layers: the infrastructure and the AI gateway. OpenFlows owns the orchestration layer. The CLI module inside the workspace is the narrow bridge between the two. GitHub and CI sit below and above the stack as external systems of record.

This separation means that improvements in Coder automatically improve OpenFlows. If Coder adds a new identity provider, OpenFlows can use it without code changes. If Coder improves workspace isolation or model governance, every OpenFlows worker benefits. OpenFlows, in turn, can focus on the hard problem of coordinating multiple agents toward a mergeable PR.

Workspace Lifecycle

The Coder integration is most visible in the workspace lifecycle. Every worker gets a fresh workspace from a template, runs a single ticket's worth of work, and is destroyed. The workspace is identified by the worker ID and the ticket ID, so NEXUS can map state back to the correct agent even if many workspaces are running concurrently.

1. Provision: NEXUS calls the Coder API to create a workspace from the configured template. The coder_module is installed automatically by the Coder Registry.
2. Bind: NEXUS creates a Chats API session bound to the workspace and assigns it to the worker identity.
3. Execute: FORGE, SENTINEL, or VESSEL runs inside the workspace via the CLI module, reading and writing files as a normal Coder user would.
4. Complete: when the ticket reaches a terminal state (merged, awaiting human, or failed recovery), NEXUS releases the worker slot.
5. Teardown: NEXUS calls the Coder API to destroy the workspace. Any local files, downloaded dependencies, or cached model outputs are deleted with it.

Extension Point: registry.json v2

The bridge between OpenFlows and Coder is configured in orchestration/agent/registry.json. The v2 schema adds explicit fields for workspace provisioning, AI Gateway routing, and per-agent CLI modules. This is the extension point for adding new models, new agent CLIs, or new Coder templates without changing the orchestrator code.

{
  "agents": {
    "forge": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "coder_module": "claude-code",
      "active": true,
      "instances": 2
    },
    "sentinel": {
      "provider": "openai",
      "model": "gpt-4.1",
      "coder_module": "codex",
      "active": true,
      "instances": 1
    }
  }
}

Why the Split Matters

Running autonomous agents inside long-lived workspaces with local secrets and accumulated context is a security and reliability anti-pattern. Coder solves the workspace problem; OpenFlows solves the coordination problem. By composing the two, OpenFlows gets enterprise-grade isolation, identity, and audit for free, and can concentrate on the orchestration logic that makes the agents useful.

For operators, the split is also a clean responsibility boundary. If a workspace fails to provision, the problem is in Coder or the template. If the wrong agent is assigned to a ticket, the problem is in OpenFlows. Debugging is simpler because each layer only worries about its own concerns.