Architecture

Honeybee’s architecture is designed around three principles: agents run cheap (edge execution), resources are shared (execution pools), and everything is observable (audit layers).

System layers

┌─────────────────────────────────────────────────────────────┐
│                    EDGE LAYER (CF Workers)                   │
│  Agent runs here: virtual FS (memfs + R2), LLM calls,       │
│  carapace scanning, ACP coordination, isomorphic-git         │
│  Cost: ~$0 (Workers are basically free)                      │
└──────────────┬──────────────────────────────────────────────┘
               │ overlay + commands (when agent needs real execution)
               ▼
┌─────────────────────────────────────────────────────────────┐
│                HONEYCOMB (Shared Execution Pool)             │
│  N always-warm workers, job queue, tag-based routing         │
│  Same cells, different honey: execution / training / build   │
│  Apply overlay → run commands → stream results → wipe → next │
│  Cost: ~90% utilization vs ~20% for per-agent containers     │
└──────────────┬──────────────────────────────────────────────┘
               │ all events flow down
               ▼
┌─────────────────────────────────────────────────────────────┐
│                    NECTAR (Audit Layer)                      │
│  Full prompt/response capture, tool execution logs,          │
│  carapace scan results, eBPF network events, FS diffs,       │
│  process trees, ACP coordination — all correlated by ID      │
│  Storage: R2 (bulk) + D1 (queryable metadata)                │
└──────────────┬──────────────────────────────────────────────┘
               │ telemetry + audit events
               ▼
┌─────────────────────────────────────────────────────────────┐
│                    HOSTED DASHBOARDS                         │
│  Carapace: fleet-wide security events, blocked injections    │
│  Nectar: agent audit trail, "what did it do and why?"        │
│  Colony: hive management, cost tracking, agent status        │
└─────────────────────────────────────────────────────────────┘

Edge execution

Most agent work is reading files, writing code, and calling LLMs. None of that requires a full server. Honeybee runs agents on Cloudflare Workers — V8 isolates that cost fractions of a cent per invocation.

The virtual filesystem gives each agent an in-memory workspace backed by R2 object storage. Reads come from cached repo snapshots. Writes go to an in-memory overlay. When the agent finishes, the overlay is the complete changeset — apply it to the real repo or discard it.

For agents that need real shell execution (npm test, cargo build), commands queue to the Honeycomb execution pool.

Honeycomb execution pool

Traditional approach: one container per agent, 80% idle time, ~$0.05/hr.

Honeycomb approach: N always-warm workers in a shared pool. Jobs queue with tags (node22, python3, gpu). Workers pick jobs matching their tags. Apply the overlay, run the command, stream results, wipe the workspace, pick the next job.

Same cells, different honey — training jobs, execution jobs, build jobs, scan jobs all share the same pool infrastructure.

Result: ~90% utilization instead of ~20%. Cost drops from ~$0.05/hr to ~$0.001/hr + per-job cost.

Coordination layer

ACP (Agent Coordination Protocol) handles all inter-agent communication:

• State: Shared key-value store. Agents read and write state without polling.
• Events: Push-based pub/sub. Agents get notified when something happens.
• Claims: Mutex locks on resources. “I’m working on this file — back off.”
• Phases: Workflow stages with exit conditions. Automatic transitions.
• Governance: Budget caps, heartbeat monitoring, approval gates.

The incubator is the server that implements ACP. It exposes REST, WebSocket, and MCP endpoints. Agents connect and coordinate through these — zero token overhead.

Security layers

Carapace scans at every boundary:

• Inbound: User input scanned before reaching agents
• Inter-agent: Messages between agents scanned for injection
• Outbound: Agent responses scanned before reaching users
• Tool calls: MCP proxy scans tool arguments and responses
• Kernel: eBPF uprobes intercept all SSL/TLS traffic on the machine

Observability

Every layer emits telemetry:

• 12 event types: llm_call, tool_call, guard_scan, agent_spawn/exit, protocol events, and more
• Local-first: Always writes JSONL to disk. Works offline.
• Cloud sync: Opt-in, sends 5-minute aggregated summaries (never raw content)
• Dashboard: Real-time metrics pushed via WebSocket every 10 seconds

Component map

Component	Package	Role
ACP Spec	@agentcoordinationprotocol/spec	Protocol format, parser, renderer
ACP SDK	@agentcoordinationprotocol/sdk	HTTP client for ACP servers
Incubator	@honeybee-ai/incubator	Coordination server, agent runner, dashboard
Carapace	@honeybee-ai/carapace	Prompt injection scanner
SDK	@honeybee-ai/hivemind-sdk	Platform client, contracts, telemetry
CLI	@honeybee-ai/waggle-cli	User-facing command line
Propolis	@honeybee-ai/propolis	Environment tools (private)
Colony	Cloudflare DO	Managed orchestration
Apiary	Node.js service	Container dispatch and health