Colony

Colony is Honeybee’s managed orchestration service. It runs agent hives on Cloudflare’s global edge network using Durable Objects — no servers to provision, no containers to manage.

What Colony does

Colony manages the full hive lifecycle:

1. Create a hive with a name and optional ACP protocol
2. Configure agents, providers, and secrets
3. Start the hive — Colony spawns agents and begins coordination
4. Monitor via CLI, SDK, or dashboard (token usage, cost tracking, agent status)
5. Stop when done — agents terminate, resources freed

# Create a hive
wgl swarm create --name my-project --protocol code-review.acp.yaml

# Set provider keys
wgl secret set cerebras --hive my-project

# Start
wgl swarm start my-project

# Monitor
wgl swarm info my-project
wgl swarm logs my-project

# Stop
wgl swarm stop my-project

Execution modes

Colony supports two execution modes:

Serverless (default)

Agents run inside Cloudflare Durable Objects. Fast startup, zero infrastructure, automatic scaling. Best for drone-type agents (ACP coordination only, no filesystem access).

Container

Agents run in Docker containers managed by Apiary (Honeybee’s container dispatch service). Full environment access — shell, git, npm, cargo, whatever the project needs. Best for worker-type agents.

# In brood.yaml
execution_mode: container  # or 'serverless' (default)

Colony routes to the right execution backend automatically.

Provider management

Colony supports all major LLM providers:

Provider	Alias	Default Model
Cerebras	fast	llama-3.3-70b
Groq	—	llama-3.3-70b
Anthropic	smart	claude-sonnet
OpenAI	—	gpt-4o
Ollama	local	llama3.3

Provider keys are stored securely in D1 with two-level resolution:

1. Hive-specific: Keys set for a specific hive override everything
2. User-level: Default keys used when no hive-specific key is set

# Set a user-level key (used by all hives)
wgl secret set cerebras

# Set a hive-specific key (overrides user-level)
wgl secret set cerebras --hive my-project

Spend tracking

Colony tracks token usage and costs per hive per month:

• Prompt tokens: Input tokens sent to the LLM
• Completion tokens: Output tokens received
• Cost (USD): Calculated from provider pricing
• Iterations: Number of agent turns completed

Usage syncs to D1 on agent completion (cost limit, max iterations, halt, or error). Query via SDK or CLI:

wgl swarm info my-project
# Shows: tokens used, cost to date, agent status, iterations

Governance enforcement

ACP governance rules are enforced by Colony at the platform level:

• Budget caps: Hard limit on total cost per hive. Agent stops when budget is exhausted.
• Max iterations: Limit on agent turns to prevent runaway loops.
• Heartbeat monitoring: Dead agents detected and resources freed.
• Cost warnings: Alert when spending reaches the warn_at threshold.

governance:
  budget:
    max_cost: 10.00
    warn_at: 0.8
  heartbeat:
    dead_after_ms: 60000

SDK integration

import { createPlatformClient } from '@honeybee-ai/hivemind-sdk';

const client = createPlatformClient({ profile: 'default' });

// List hives
const hives = await client.listHives();

// Create a hive
const hive = await client.createHive({ name: 'my-project' });

// Set secrets
await client.setSecret({ provider: 'cerebras', key: 'csk-...' });

// Start/stop
await client.startHive(hive.id);
await client.stopHive(hive.id);