Incubator

The incubator is Honeybee’s coordination engine. It’s an HTTP/WebSocket server that implements the ACP protocol, manages agents, and provides a real-time dashboard.

What it does

• ACP server: REST + WebSocket + MCP endpoints for state, events, claims, messages, control
• Agent orchestrator: Spawns and manages agents from brood.yaml configuration
• Carapace guard: Auto-scans all reads/writes for prompt injection
• Dashboard: React 19 real-time UI with 7 tabs (state, events, agents, claims, control, config, metrics)
• Dance runtime: Loads custom tool handlers (game logic, state machines)
• Static serving: Serves demo UIs alongside the API

Quick start

# Start a coordination server
wgl serve --port=8080 --verbose

# With a protocol
wgl serve --port=8080 --protocol=spec.acp.yaml

# With brood (full orchestration)
wgl up

# With dances and static UI
wgl serve --port=8080 \
  --brood=brood.yaml \
  --dances=game.js \
  --static=./ui

See the full Incubator Quick Start for more.

Architecture

REST API (/api/*)
  ├── State store (get/set key-value pairs)
  ├── Event store (publish/subscribe)
  ├── Claim store (mutex locks)
  ├── Message store (agent-to-agent)
  ├── Role store (agent registration)
  ├── Control (halt/pause/resume)
  └── Dance endpoint (custom tool calls)

WebSocket (/ws)
  ├── Real-time event push
  ├── dance_call / dance_result
  ├── Reset
  └── Metrics push (every 10s)

MCP endpoint (/mcp)
  └── Model Context Protocol server

Dashboard (/dashboard)
  └── React 19 UI (7 tabs)

Orchestrator
  ├── BroodOrchestrator (reads brood.yaml)
  ├── AgentPool (manages agent processes)
  ├── DirectRuntime (in-process agents)
  └── Plugin system (auto-discovers propolis)

Agent types

Type	Execution	Tools	Use case
worker	In-process	Full propolis (file, shell, git, web, PTY)	Building, testing
drone	MCP subprocess	ACP only	Review, voting
claude	Claude Agent SDK	Full Claude Code tools	Complex reasoning
mock	Action sequences	Dispatches to real stores	Testing without LLM

CLI flags

Always use = syntax (not space-separated):

Flag	Description
--port=N	Listen port (default: 3100)
--verbose	Detailed logging
--tls-cert=PATH	TLS certificate
--tls-key=PATH	TLS private key
--brood=PATH	Brood YAML config
--dances=PATH	Dance file (ESM module)
--static=DIR	Serve static files
--protocol=PATH	Load ACP protocol
--backend=TYPE	Storage: memory, sqlite, redis
--db=PATH	SQLite path
--no-guard	Disable Carapace scanning
--mode=TYPE	http (default) or mcp (stdio)
--log-format=json	Structured JSONL logging

Plugin system

The incubator uses a plugin architecture for extensibility. Plugins implement IncubatorPlugin from @honeybee-ai/hivemind-sdk/integrations:

interface IncubatorPlugin {
  name: string;
  getToolEntries(ctx: PluginContext): ToolEntry[];
  start?(ctx: PluginContext): Promise<void>;
  stop?(): Promise<void>;
}

Propolis (environment tools) is auto-discovered at boot. Additional plugins load via brood.yaml or --plugin flag.

Package

npm install @honeybee-ai/incubator

Export	What
Default	Library exports (stores, orchestrator, types)
Binary (incubator)	CLI entry point