OpenMOSS: How I Built a Multi-Agent Orchestration System for My AI Stack

Building individual AI agents is the easy part. I've been doing it for two years out of Allen, TX — BellaBot handles call screening for VIXI clients, HyrosBot pulls attribution data, DevBot manages deploy pipelines, and Orus sits at the center coordinating everything. On paper, that sounds like a mature AI stack. In practice, it was organized chaos.

Here's what coordination actually looked like before OpenMOSS: I would open a session with Orus, describe what I needed, and then manually tell it to hand off to DevBot, wait for DevBot to finish, then relay results back to Orus for the next step. Each agent lived in its own workspace with its own memory, tools, and context. They couldn't see each other. There was no shared task state.

The pain hit hardest when I onboarded a new VIXI client integration last month. The work required four agents in sequence: HyrosBot to pull account data, DevBot to scaffold the integration, Orus to write the client brief, and BellaBot to be reconfigured with client-specific scripts. I coordinated all of it manually across three sessions. When DevBot failed halfway through, I lost track of what had been done. I started over from memory.

That's the coordination tax. You don't see it on an invoice but you pay it every day in lost time, duplicated work, and brittle processes that depend on you being in the loop.

What I actually needed was simple: a task queue with agent routing, deliverable tracking, status visibility, and retry logic. Something that treats agents like workers clocking in and out, not like scripts you run by hand.

OpenMOSS is a self-hosted multi-agent orchestration system. Not a no-code tool. Not n8n. Not a cloud SaaS with a per-seat pricing page. It's a REST API that sits between my agents and their work, providing a shared task graph that every agent can read from and write to.

The data model is clean. Four objects:

The key design decision that makes MOSS different from a regular job queue: agents pull work, MOSS doesn't push. An agent claims a subtask when it's ready. It executes. It submits a deliverable. MOSS records the result and updates status. This pull model means agents are autonomous — they decide when to pick up work, and MOSS just keeps score.

The claim → execute → submit lifecycle looks like this in practice:

# 1. Claim a subtask (agent signals it's working on this)
curl -X POST http://localhost:6565/api/sub-tasks/{subtask_id}/claim \
  -H "Authorization: Bearer {agent_api_key}"

# 2. Execute the work (agent does actual work here)
# ... agent reads outline, writes file, calls APIs ...

# 3. Submit deliverable (agent records what it produced)
curl -X POST http://localhost:6565/api/sub-tasks/{subtask_id}/submit \
  -H "Authorization: Bearer {agent_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"deliverable": "/path/to/output/file.tsx"}'

# 4. Mark complete
curl -X POST http://localhost:6565/api/sub-tasks/{subtask_id}/complete \
  -H "Authorization: Bearer {agent_api_key}"

Four API calls. That's the entire agent integration surface. The simplicity is intentional — any agent that can make HTTP requests can participate in MOSS.

I installed OpenMOSS on March 17, 2026, on the same Mac that runs Mission Control and the OpenClaw gateway. Here's the real walkthrough — not the happy path, but what actually happened.

Prerequisites

Node.js 20+, a Postgres instance (or SQLite for local dev), and a machine that stays on. I run everything on an M-series Mac with an ExternalSSD mounted at /Volumes/ExternalSSD — same setup as Mission Control and my project files.

Install

git clone https://github.com/[openmoss-repo]
cd openmoss
npm install
cp .env.example .env

Key env vars to set: DATABASE_URL, MOSS_API_KEY, and PORT. I run MOSS on port 6565 to avoid conflicts with Mission Control on 3000 and other local services.

First npm run dev gave me a migration error — the database tables didn't exist yet. That's expected. The docs say to run migrations first, but the README buries that step. Run this before starting the server:

npm run migrate
# Creates: tasks, sub_tasks, modules, agents tables
# Note: all primary keys are UUIDs, not integers
# This matters when you write queries or agent code

Registering Agents

Each agent needs to be registered before it can claim tasks. I registered three on day one: orus-main, devbot, and moss-executor. The registration payload:

// POST /api/agents
{
  "name": "moss-executor",
  "description": "Lightweight Claude Code agent. Claims and executes specific subtask types: file writes, API calls, research.",
  "capabilities": ["file_write", "web_research", "api_calls", "code_generation"],
  "api_key": "ak_your_key_here"
}

// Response includes agent UUID — store this, you need it
// when creating subtasks with assigned_agent field

Creating Your First Task

Here's the exact payload I used to create the task that produced this blog post. It's recursive in a satisfying way — MOSS orchestrated writing its own documentation:

// POST /api/tasks
{
  "title": "OpenMOSS Blog Post",
  "description": "Write and publish a blog post about OpenMOSS installation and architecture",
  "module_id": "marketing-module-uuid",
  "priority": "high"
}

// POST /api/sub-tasks
{
  "task_id": "task-uuid-from-above",
  "name": "Write TSX blog post",
  "description": "Write complete page.tsx for /blog/openmoss-multi-agent-orchestration/",
  "assigned_agent": "moss-executor-uuid",
  "deliverable": "File path to completed page.tsx",
  "acceptance": "File exists, matches dark slate theme, ~2000 words",
  "priority": "high"
}

Registering agents is the easy part. The interesting part is making Orus — my primary Claude agent — actually aware of and able to use MOSS as its work queue. This required working around a real constraint in my stack.

The OpenClaw Gateway Problem

Orus runs via OpenClaw, which provides gateway tools for reading files, writing files, and executing shell commands. On my macOS arm64 setup, the write and edit gateway tools are unreliable — they report success but changes don't persist. I covered this in my Claude API agents post, where I documented the fix: a wrapper script called claude_exec.js that spawns Claude Code CLI, which has native filesystem tools that actually work.

The same pattern applies to MOSS integration. Orus uses the exec gateway tool (which does work reliably) to call claude_exec.js, which then spawns a Claude Code session to handle the actual MOSS API calls and file operations.

MOSS as Orus's Work Queue

I added the MOSS API surface to Orus's TOOLS.md — the document that describes what tools Orus knows about and how to use them. The key additions:

## MOSS — Multi-Agent Orchestration System
Base URL: http://localhost:6565
Auth: Bearer {MOSS_API_KEY}

### List pending subtasks assigned to orus-main
GET /api/sub-tasks?assigned_agent={orus_agent_id}&status=pending

### Claim a subtask
POST /api/sub-tasks/{id}/claim

### Submit deliverable
POST /api/sub-tasks/{id}/submit
Body: { "deliverable": "result text or file path" }

### Mark complete
POST /api/sub-tasks/{id}/complete

### Create new subtask (for delegation)
POST /api/sub-tasks
Body: { task_id, name, description, assigned_agent, deliverable, priority }

Now Orus has a morning routine: check MOSS for pending subtasks assigned to orus-main, claim the highest priority one, execute it via Claude Code, submit the deliverable, move to the next. It's not fully autonomous yet — Orus still needs a trigger — but the work queue is real.

The Executor Agent Pattern

Not every subtask needs Orus's full context window and system prompt. Some just need file writes, API calls, or research. That's what moss-executor is for — a lightweight Claude Code agent that claims and runs specific subtask types without loading Orus's entire knowledge base.

The executor pattern: MOSS assigns the subtask to moss-executor. A scheduled check (or manual trigger) spawns a Claude Code session with a minimal prompt: here's the subtask ID, here's the MOSS API key, claim it, read the description, do the work, submit the deliverable. That's it.

This is actually how this blog post got written. Orus created the outline, assigned the writing subtask to moss-executor, and executor claimed it, read the outline, and produced this file. First end-to-end agent handoff in my stack that didn't require me in the middle.

The claim → execute → submit pattern sounds simple. Here's what it actually makes possible in a real AI stack:

1. Blog Content Pipeline

One task = one post. Subtasks in sequence: research topic → write outline → draft full post → SEO review → save and publish. Each subtask assigned to the agent best suited for it. Orus handles research and outline (needs full business context), executor handles the write (just needs the outline). The handoff is a MOSS deliverable, not a Slack message to myself.

2. Client Onboarding Automation

New VIXI client integration = new MOSS task. Subtasks for: pull Hyros account data, scaffold integration code, configure BellaBot scripts, run smoke tests, write client brief. Each one assigned to the right agent with a clear deliverable spec. No more manual checklist in Notion that I forget to update.

3. Daily DevOps

DevBot's morning subtasks live in MOSS: check deploy logs, run smoke tests on Mission Control, report anomalies to Orus. MOSS becomes the source of truth for what DevBot checked and what it found. When something breaks at 3am, I have an audit trail, not a mystery.

4. Async Parallelism

This is the one that changes the math. Two agents can work on different subtasks within the same task simultaneously. While executor is writing this blog post, Orus can be working on a different subtask in the same Marketing module. First real parallel agent execution in my stack. Previously impossible without MOSS because there was no shared state to coordinate around.

5. Incident Response

When a deploy fails, Orus creates a MOSS task with subtasks: diagnose root cause, implement fix, run tests, redeploy, verify. Full audit trail of what each agent attempted and what it delivered. The task doesn't close until all subtasks are complete. No more "I think DevBot fixed it" — MOSS says definitively what got done.

I didn't build this from scratch without looking at what exists. Here's the honest comparison:

The key distinction: MOSS treats agents as first-class workers. Every other tool on that list was designed for humans or for simple API calls. MOSS has an agent registry, agent-scoped API keys, a claiming model that prevents duplicate work, and a deliverable system that creates accountability. None of the alternatives have all four.

Honest retrospective after day one:

Start with the schema. I spent the first hour building agents before I fully understood the tasks → modules → subtasks hierarchy. When I realized subtasks needed a module_id → task_id chain, I had to redo my first three test tasks. Read the data model before you write a line of integration code.

Version your deliverable format. The subtask deliverable field is freeform text. I have subtasks where the deliverable is a file path, subtasks where it's a JSON summary, and subtasks where it's a multi-paragraph report. That inconsistency will hurt when I try to build automated verification. I should standardize a JSON schema per subtask type early.

Don't skip the agent registry. I almost hardcoded agent IDs directly in my scripts. The registry pays off the moment you add agent #4 or rotate an API key. Treat agent IDs as configuration, not constants.

Set acceptance criteria upfront. The acceptance field on subtasks is optional in MOSS but invaluable for automated verification. When I left it blank on early subtasks, I had no machine-readable way to confirm the deliverable met requirements. I'm now filling it in for every subtask I create.

Next step: Mission Control integration. Right now I check MOSS task status via curl. The next integration I'm building is surfacing MOSS task progress in Mission Control's dashboard, so I can see all agent work from one UI instead of context-switching between the MC web app and the MOSS API.

I've been building AI agents for two years. MOSS is the first time they feel like a team instead of a collection of scripts that happen to share a filesystem. The difference isn't the technology — it's the model. When every agent has a work queue, a deliverable contract, and a completion signal, you stop managing agents and start managing outcomes.

The claim → execute → submit pattern is deceptively simple. But it changes everything about how you design agent work. Instead of "have Orus do this," you ask: what's the deliverable? Who's the right agent? What does done look like? Those questions force clarity that makes every subsequent step faster.

If you're running more than two or three agents and manually coordinating them, you're already paying the coordination tax. You just don't see it on an invoice. MOSS made mine visible — and then made it smaller.