Agent Setup

OpenFlows agents are configured through two files: .env for Coder credentials and runtime settings, and orchestration/agent/registry.json for agent definitions, model routing, and Coder workspace provisioning. Run openflows-setup to generate both interactively, or write them manually.

In Coder mode, each agent runs inside an ephemeral Coder workspace that is provisioned when a task is assigned and torn down after merge. The registry controls which LLM each agent uses (via the Coder AI Gateway), which Coder Registry module installs the code agent CLI, and how many parallel worker instances to run.

registry.json - The Single Source of Truth

See registry.json Schema for the complete configuration reference. The file defines workspace_provider, ai_gateway routing, and per-agent settings.

Top-Level Fields

Field	Type	Description
`workspace_provider`	string	`"coder"` - tells OpenFlows to provision ephemeral Coder workspaces instead of local Git worktrees.
`coder_module`	string	Default Coder Registry module that installs the code agent CLI into every workspace (e.g. `"claude-code"`, `"codex"`, `"aider"`). Overridden per-agent.
`ai_gateway.primary`	string	`"coder"` - route all LLM calls through the Coder AI Gateway. API keys are managed centrally and never exposed inside workspaces.
`ai_gateway.fallback`	string	`"litellm"` - fall back to a LiteLLM proxy when the Gateway is unavailable (air-gapped or self-hosted providers).

Per-Agent Fields

Each key under agents is an agent role. The fields below apply to every agent entry.

Field	Type	Description
`provider`	string	LLM provider for this agent: `anthropic`, `openai`, `google`, `fireworks`, `groq`, etc.
`model`	string	Model identifier passed to the provider via the AI Gateway (e.g. `claude-sonnet-4-20250514`).
`coder_module`	string	Per-agent override of the top-level `coder_module`. Lets FORGE run `claude-code` while LORE uses `aider`.
`active`	bool	Set `false` to exclude the agent from orchestration entirely.
`instances`	int	Number of parallel worker slots. FORGE with `instances: 2` → `forge-1`, `forge-2`, each in its own Coder workspace.

Mixing CLI modules across agents

The coder_module field is set per-agent, so you can mix CLIs across roles. FORGE can run claude-code while SENTINEL uses codex and LORE uses aider - each gets the right tool for the job. The top-level coder_module acts as a default; per-agent values override it.

Common Operations

Scale FORGE workers:

json

"forge": { "instances": 4 }
// → forge-1, forge-2, forge-3, forge-4
// Each gets its own ephemeral Coder workspace.

Disable an agent:

json

"lore": { "active": false }
// LORE will not be invoked

Switch an agent to a different model:

json

"sentinel": { "provider": "google", "model": "gemini-2.5-pro" }
// SENTINEL now uses Gemini via the AI Gateway

Use a different CLI for one agent:

json

"forge": { "coder_module": "aider" }
// FORGE now uses Aider instead of Claude Code

GitHub identity (handled by Coder):

bash

# In Coder mode, GitHub identity is handled by Coder external auth.
# Each agent inherits its GitHub identity from the logged-in Coder
# user via the git-config module  -  nothing to configure in registry.json.
# Configure a GitHub external auth provider in your Coder deployment.

Recommended Model Assignments

These defaults balance reasoning quality, cost, and adversarial review. Mixing providers (Anthropic for FORGE, OpenAI for SENTINEL) creates natural adversarial review - the code reviewer uses a different model family than the code writer.

Agent	Provider / Model	CLI Module	Why
`FORGE`	anthropic / claude-sonnet-4-20250514	claude-code	Primary coding agent - needs top-tier reasoning
`NEXUS`	anthropic / claude-sonnet-4-20250514	claude-code	Orchestrator – needs reliable decision-making
`SENTINEL`	openai / gpt-4.1	codex	Code review – strong reasoning, different provider for adversarial review
`VESSEL`	openai / gpt-4o	codex	CI/CD scripting – fast and cost-effective
`LORE`	anthropic / claude-haiku-4-20250514	aider	Documentation – lightweight task, lightweight model

Hot Reload

registry.json is re-read on every NEXUS poll cycle - no restart required when you change instances, models, CLI modules, or active flags.

Ephemeral workspace lifecycle

When NEXUS assigns a ticket to a FORGE worker, it provisions a fresh Coder workspace from your template. The coder_module installs the CLI code agent into that workspace. After the PR is merged, the workspace is torn down - no lingering state, no stale credentials, no disk bloat. Each parallel FORGE instance gets its own workspace.