registry.json Schema

orchestration/agent/registry.json is the single source of truth for the OpenFlows agent team. Version 2 of the schema separates runtime provisioning from model routing and makes every agent role independently configurable. This page documents every top-level field, every per-agent field, and the nested skills and mcp structures.

The registry is read on every NEXUS poll cycle. You can change models, scale instances, swap CLI modules, add skills, or disable agents without restarting the orchestrator. The extension point is intentionally simple: edit JSON, and the next cycle picks up the new configuration.

Default registry.json

The following file is the recommended starting point. It uses the Coder workspace provider, the Claude Code CLI module by default, the Coder AI Gateway as the primary LLM path, and LiteLLM as an air-gapped fallback. The five agent roles are NEXUS, FORGE, SENTINEL, VESSEL, and LORE.

Top-Level Fields

AI Gateway Fields

The ai_gateway object controls where LLM calls go. OpenFlows does not hold provider credentials; it passes the per-agent provider and model values to the gateway, which handles authentication and audit.

Per-Agent Fields

Every key under agents is a role name. The five built-in roles are nexus, forge, sentinel, vessel, and lore. You can add new roles if the Coder modules and skills exist, but the built-in flow expects these five.

Skills Array

Skills are plug-and-play knowledge packs. Each entry is a directory under orchestration/plugin/skills/ that contains a SKILL.md manifest and any supporting files. Adding a skill to an agent does not require any code change; the skill is symlinked into the workspace at provisioning time.

A skill entry can be a simple string (the directory name, enabled by default) or an object with an explicit enabled flag. Disabled skills are still loaded into the skill registry but are not injected into the agent's workspace.

MCP Object

The mcp object registers Model Context Protocol servers for an agent. MCP servers can be defined locally (command-based) or referenced from the Coder dashboard (central registration). Central servers are preferred for secrets and versioning; local servers are useful for development and one-off tools.

Validation Rules

The orchestrator validates the registry at load time and on every hot reload. Invalid configurations are logged and the previous valid configuration is retained. This prevents a typo from stopping the entire team.

# Validate the registry without starting the orchestrator
openflows doctor registry

Common Configuration Changes

Scale FORGE workers:

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

Disable an agent:

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

Switch an agent to a different model:

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

Use a different CLI for one agent:

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

Register a new skill:

"forge": { "skills": ["forge-coding", "rust-patterns"] }
// The rust-patterns skill is loaded into every FORGE workspace

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 reviewer uses a different model family than the code writer.