Broodlink

Broodlink lets multiple AI agents work together. Instead of one AI working alone, Broodlink connects several agents — each with different strengths — so they can share knowledge, delegate tasks to each other, and coordinate their work through a single system.

How it works: Every agent connects to a central tool API (beads-bridge) using JWT authentication. When an agent stores a memory, creates a task, or sends a message, beads-bridge routes it to the right database. A coordinator service watches for new tasks and assigns them to the best available agent. A heartbeat service keeps everything healthy. All communication flows through NATS messaging, so agents stay decoupled and the system scales naturally.

Copyright (C) 2025-2026 Neven Kordic [email protected]

Install

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nevenkordic/broodlink/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nevenkordic/broodlink/main/install.ps1 | iex

Then run broodlink — the setup wizard handles everything else (Ollama, Postgres, Qdrant, model downloads).

To uninstall:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nevenkordic/broodlink/main/install.sh | sh -s -- --uninstall

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nevenkordic/broodlink/main/install.ps1))) -Uninstall

From Source

# Recommended: use broodctl to manage the stack
./broodctl up          # Start everything (infrastructure + services)
./broodctl status      # Check full stack status
./broodctl health      # Verify all health endpoints
./broodctl rebuild     # Build from source + restart
./broodctl down        # Stop everything

# First-time setup from scratch
bash scripts/bootstrap.sh

After startup, you'll have:

Architecture

                    Agents (Claude, Gemma4, custom bots, ...)
                            │
                    ┌───────▼───────┐
                    │ beads-bridge  │ :3310  Tool API (96 tools)
                    │               │   JWT RS256 + Rate Limiting
                    └──┬────┬───┬──┘
                       │    │   │
          ┌────────────┘    │   └────────────┐
          │                 │                │
  ┌───────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
  │    Dolt      │  │  Postgres   │  │    NATS     │
  │  :3307       │  │  :5432      │  │  :4222      │
  │ (versioned)  │  │ (hot paths) │  │ (messaging) │
  └──────────────┘  └──────┬──────┘  └──────┬──────┘
                           │                │
                    ┌──────▼──────┐  ┌──────▼──────┐
                    │ embedding-  │  │ coordinator │
                    │ worker      │  │             │
                    └──────┬──────┘  └─────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
      ┌───────▼──┐  ┌─────▼────┐  ┌───▼────────┐
      │  Ollama  │  │  Qdrant  │  │ heartbeat  │
      │  :11434  │  │  :6333   │  │ (5m cycle) │
      └──────────┘  └──────────┘  └────────────┘

  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │  status-api  │  │  mcp-server  │  │ a2a-gateway  │
  │  :3312       │  │  :3311       │  │  :3313       │
  └──────┬───────┘  └──────────────┘  └──────────────┘
         │
  ┌──────▼───────┐
  │  Hugo Site   │
  │  :1313       │
  └──────────────┘

Data Flow

1. Tool calls -- Agent sends POST to /api/v1/tool/<name> -- beads-bridge validates JWT (kid-based multi-key), checks rate limits, guardrails, and budget, writes audit log, dispatches to Dolt or Postgres
2. Memory + embeddings + search -- store_memory inserts to Dolt + Postgres full-text index + outbox row -- embedding-worker polls outbox every 2s -- smart chunk splitting at heading/code-fence/paragraph boundaries -- Ollama generates vector per chunk -- Qdrant upsert -- extracts entities/relationships via LLM and stores in knowledge graph (Postgres kg_entities/kg_edges + Qdrant broodlink_kg_entities) -- hybrid_search and semantic_search expand queries via Ollama (2-3 alternative phrasings), run each variant in parallel, merge by max score -- BM25 (Postgres tsvector) + vector (Qdrant) fusion with temporal decay and optional reranking -- graph_search/graph_traverse query the knowledge graph -- graceful degradation to BM25-only or vector-only if a backend is down -- delete_memory cleans up Dolt, Postgres, and Qdrant vectors
3. Task routing -- create_task writes to Postgres + publishes NATS -- coordinator scores all eligible agents (success rate, load, cost, recency), excludes declined agents -- claims atomically -- dispatches to winning agent -- agents can decline_task (re-routes, max 3 declines then dead-letter) or request_task_context (pauses task, publishes questions, auto-resets on timeout) -- failed tasks land in dead-letter queue with auto-retry (exponential backoff)
4. Workflow orchestration -- start_workflow creates a workflow_runs row + publishes NATS -- coordinator loads formula TOML -- supports conditional steps (when expressions), per-step retries, parallel step groups, step timeouts, and on_failure error handlers -- all step results collected in step_results JSONB
5. Multi-agent collaboration -- coordinator auto-decomposes complex tasks into sub-tasks via LLM before routing (configurable, fail-open) -- agents can delegate sub-tasks to other agents through the coordinator (request/accept/decline/complete lifecycle) -- completed task outputs are automatically verified by LLM (pass/fail with feedback/skip) -- parent tasks auto-complete when all children finish -- create_workspace + workspace_read/workspace_write for shared context
6. Budget enforcement -- check_budget middleware deducts tokens per tool call -- set_budget/get_budget tools for management -- daily replenishment via heartbeat -- BudgetExhausted error (402) blocks calls when depleted
7. Webhook gateway -- a2a-gateway receives Slack slash commands, Teams bot messages, Telegram updates -- parses /broodlink <command> into tool calls -- outbound notifications for agent.offline, task.failed, budget.low, workflow events, guardrail violations
8. Conversational gateway (v0.7.0) -- a2a-gateway receives Slack/Teams/Telegram messages → creates chat sessions → routes to coordinator for task creation → delivers replies via platform-specific APIs -- list_chat_sessions/reply_to_chat tools for agent interaction -- direct Ollama LLM chat with 10 tools: web_search (Brave), fetch_webpage (direct HTTP GET), remember, schedule_task, list_scheduled_tasks, cancel_scheduled_task, read_file, write_file, read_pdf, read_docx -- auto-fetch from history (v0.11.0): DB query finds URLs from past messages beyond the context window, fetches the most recent, injects content into system prompt — no tool calling needed -- retry with reduced tools (v0.11.0): when model exhausts thinking budget, retries with 3-tool set and last 6 conversation turns -- streaming responses (v0.11.0): Telegram messages stream progressively via editMessageText (~1 edit/800ms, 30-token minimum), tool calls pause stream and show indicator -- multi-Ollama load balancing (v0.11.0): OllamaPool distributes inference across multiple instances (least-loaded healthy, 30s health probe, auto-recovery) -- multi-modal attachments (v0.11.0): Slack file uploads (via url_private + bot token), Telegram photos/documents (via getFile API), and Teams attachments are downloaded, classified (image/audio/video/document), stored to attachments_dir, and persisted in chat_attachments table -- efficiency safeguards: concurrency semaphore, Brave search result cache (5-min TTL), duplicate message suppression (30s dedup), typing indicator refresh (4s) -- busy/dedup replies excluded from conversation history -- Telegram access code authentication -- cascade delete on bot disconnect -- NATS-based credential cache invalidation -- self-healing model failover: on OOM, tries recovery (unload → retry), if still failing enters degraded mode (fallback model answers questions directly), probes primary model every 5 min -- verification timeout caveat (v0.11.0): timed-out verifications append [Unverified] instead of silently passing
9. Formula registry (v0.7.0) -- bidirectional sync between TOML files and Postgres formula_registry -- system formulas (.beads/formulas/*.formula.toml) synced to Postgres by heartbeat (TOML wins, definition_hash skip when unchanged) -- user formulas written through to custom/ TOML on every create/update -- custom TOML backfilled to Postgres on startup (insert only, never overwrite) -- heartbeat safety net rewrites missing user formula TOMLs within one cycle -- system formulas are immutable via API (must copy to new name) -- name collision guard prevents user formulas from shadowing system names -- list_formulas/get_formula/create_formula/update_formula tools for CRUD
10. Dashboard auth (v0.7.0) -- session-based RBAC (viewer/operator/admin) -- bcrypt passwords, session tokens in Postgres -- API key fallback when auth disabled -- role enforcement in JS control panel
11. Heartbeat cycle (every 5 min) -- Dolt commit, agent metrics computation, daily summary generation, stale agent deactivation, memory search index sync (Dolt → Postgres), knowledge graph backfill, KG entity/edge expiry with weight decay, daily budget replenishment, chat session expiry, dashboard session cleanup, formula registry sync (system TOML → Postgres, custom TOML backfill, hash backfill, disk safety net), notification rule evaluation (service_event_error, dlq_spike, budget_low conditions with cooldown and auto-postmortem)
12. Scheduled task promotion -- coordinator polls scheduled_tasks every 60 seconds -- promotes due tasks into task_queue -- supports one-shot (disable after fire) and recurring (next_run_at += recurrence_secs) -- optional formula execution -- publishes NATS task_available for immediate routing
13. Notification dispatch -- send_notification tool inserts notification_log + publishes NATS notification.send -- a2a-gateway subscribes and delivers to Telegram (bot API) or Slack (incoming webhook) -- delivery status tracked as pending/sent/failed

Databases

Services

Shared Crates

Configuration

All configuration lives in config.toml. Every field can be overridden with environment variables using the BROODLINK_ prefix:

Deployment Profiles

• dev: TLS off, SOPS secrets provider, relaxed audit residency
• prod: Mutual TLS on inter-service connections, Infisical secrets provider, strict audit residency, NATS clustering, Postgres read replicas

Testing

cargo test --workspace                    # 381 unit tests
bash tests/run-all.sh                     # 22 integration test suites
bash tests/e2e.sh                         # 124 end-to-end tests (requires running services)
bash tests/v060-regression.sh             # 164 v0.6.0 regression tests

The E2E suite covers: service health, JWT/API key auth, all tool categories, status API endpoints, background service verification, SSE streaming, NATS integration, error handling, database round-trips, semantic search, hybrid memory search, knowledge graph tools, chat sessions, and login page. The v0.6.0 regression suite covers: budget enforcement, DLQ tooling, OTLP telemetry, KG expiry, JWT rotation, workflow branching, dashboard control panel, multi-agent collaboration, and webhooks. v0.7.0 adds chat integration, formula registry, and dashboard auth test suites. v0.11.0 adds onboarding regression tests (agent_id validation, JWT claims, tilde expansion, payload defaults).

Benchmarks

Measured on Mac Studio — Apple M4 Max, 16 cores (12P + 4E), 128 GB unified memory.

Ollama Models

vs Cloud Models (published benchmarks)

Local models achieve ~85-95% of cloud quality at zero cost, zero latency, full privacy.

Services & Databases

Platforms

Pre-built binaries for all platforms — no build tools required:

Download from the latest release, or use the one-liner install scripts above. All archives include SHA256 checksums. Push a version tag (git tag vX.Y.Z && git push origin vX.Y.Z) to trigger the release workflow.

Prerequisites

• Rust 1.75+ with cargo-deny
• Hugo 0.120+ (extended edition)
• age + SOPS (secrets management)
• Dolt SQL server
• PostgreSQL 15+
• NATS 2.10+
• Qdrant 1.7+
• Ollama with nomic-embed-text model
• Python 3.10+ (for agent SDK)

Scripts

Directory Structure

broodlink/
├── crates/
│   ├── broodlink-config/         # Configuration loading + validation
│   ├── broodlink-events/         # Streaming event protocol (SSE/NATS typed envelopes)
│   ├── broodlink-secrets/        # SecretsProvider trait + implementations
│   ├── broodlink-telemetry/      # OpenTelemetry + OTLP export
│   ├── broodlink-runtime/        # CircuitBreaker, shutdown_signal, connect_nats
│   ├── broodlink-formulas/       # Formula TOML parsing, JSONB conversion, sync helpers
│   └── broodlink-fs/             # File system helpers, attachment storage
├── rust/
│   ├── broodlink/                # Unified binary: setup wizard, process manager, dashboard, chat UI
│   ├── beads-bridge/             # Universal tool API (96 tools, task negotiation)
│   ├── coordinator/              # NATS task routing + workflow orchestration + decomposition + delegation + verification
│   ├── heartbeat/                # Periodic sync + health checks
│   ├── embedding-worker/         # Outbox → Ollama → Qdrant pipeline + KG entity extraction
│   ├── status-api/               # Dashboard API + control panel endpoints
│   ├── mcp-server/               # MCP protocol server
│   └── a2a-gateway/              # A2A protocol gateway + webhook gateway
├── agents/                       # Python SDK: typed clients, Click CLI, BaseAgent framework, ML utilities
├── status-site/                  # Hugo dashboard (WCAG 2.1 AA, 18 pages)
│   └── themes/broodlink-status/  # 18 pages
├── install.sh                    # One-liner installer (macOS/Linux)
├── install.ps1                   # One-liner installer (Windows)
├── broodctl                      # Stack manager (up/down/status/rebuild/doctor)
├── migrations/                   # SQL migrations (33 files, additive only)
│   ├── 001_dolt_brain.sql
│   ├── 002_postgres_hotpaths.sql
│   ├── 003_postgres_functions.sql
│   ├── 004_approval_gates.sql
│   ├── 005_agent_metrics.sql
│   ├── 005b_agent_max_concurrent.sql
│   ├── 006_negotiations.sql
│   ├── 007_streams.sql
│   ├── 008_guardrails.sql
│   ├── 008b_agent_budget_tokens.sql
│   ├── 009_a2a_gateway.sql
│   ├── 010_task_result.sql
│   ├── 011_workflow_orchestration.sql
│   ├── 012_memory_fulltext.sql
│   ├── 013_knowledge_graph.sql
│   ├── 014_budget_enforcement.sql
│   ├── 015_dead_letter_queue.sql
│   ├── 016_workflow_branching.sql
│   ├── 017_multi_agent_collab.sql
│   ├── 018_webhooks.sql
│   ├── 019_chat_sessions.sql
│   ├── 020_formula_registry.sql
│   ├── 021_dashboard_auth.sql
│   ├── 022_schema_hardening.sql
│   ├── 023_platform_credentials.sql
│   ├── 024_platform_credentials_meta.sql
│   ├── 025_missing_indexes.sql
│   ├── 026_formula_sync.sql
│   ├── 027_service_events.sql
│   ├── 028_proactive_skills.sql
│   ├── 029_negotiation_protocol.sql
│   ├── 030_chat_attachments.sql
│   └── 031_runtime_settings.sql
├── tests/                        # Integration + E2E test suites
├── templates/                    # System prompt template for agent onboarding
├── scripts/                      # Build, setup, onboarding, and dev scripts
├── launchagents/                 # macOS LaunchAgent plists (8 services)
├── .beads/formulas/              # Workflow formula definitions
│   └── custom/                   # User-created formulas (auto-persisted from Postgres)
├── .secrets/                     # Encrypted secrets (age + SOPS)
├── config.toml                   # Application configuration
├── deny.toml                     # cargo-deny license/ban rules
├── podman-compose.yaml           # Container orchestration (optional, dev only)
└── podman-compose.prod.yaml      # Prod containers: 3-node NATS, PG replicas, TLS

Beads Workflow Formulas

Located in .beads/formulas/:

Visual Workflow Editor

The dashboard includes a drag-and-drop visual editor at /workflows/ for authoring and editing formulas. Built with custom SVG (no external JS dependencies):

• Canvas: Zoom/pan, port-to-port edge drawing, node dragging, snap-to-grid, auto-layout (Kahn's topological sort)
• Node types: Step (rect), Condition (diamond), Start/End (circles) with role badges and tool count indicators
• Property panel: All FormulaStep fields including searchable tool multi-select, agent role, prompt, output schema, error handler
• Validation: Real-time cycle detection (DFS), duplicate name checks, empty field warnings — blocks save on errors
• Serialization: Bidirectional Formula ↔ graph conversion preserving all step fields, parallel groups, and conditional edges
• Persistence: Node positions saved to localStorage keyed by formula name; undo/redo with debounced history stack

Security

Broodlink applies defence-in-depth across all services:

External Integrations

• MCP: Agents connect via the mcp-server, which proxies all 96 bridge tools over MCP protocol (streamable HTTP or stdio transport) with JWT authentication
• A2A: The a2a-gateway implements Google's Agent-to-Agent protocol -- exposes an AgentCard at /.well-known/agent.json, accepts task delegation from external A2A-compatible agents, and bridges them to internal Broodlink tasks
• Webhooks: The a2a-gateway also serves as a webhook gateway -- receives Slack slash commands (/broodlink agents), Teams bot messages, and Telegram bot updates -- parses commands into bridge tool calls -- sends outbound notifications (agent.offline, task.failed, budget.low, workflow events, guardrail violations) to configured webhook endpoints

License

GNU Affero General Public License v3.0 or later -- see LICENSE.