A self-hosted blackboard multi-agent system.
Stigmergic coordinates model-backed agents through durable, versioned runtime contracts. The product uses the bMAS architecture.
This repository includes three runtimes. Classic uses a control unit and a shared blackboard. Patchboard integrates independent contributions. Stigmergic workspace applies ordered revisions to one shared artifact.
You need Docker 24 or newer, Docker Compose 2.20 or newer, and one provider API key.
git clone https://github.com/arvarik/bmas.git
cd bmas
./scripts/bmas init --provider gemini
./scripts/bmas up
./scripts/bmas smokeThe init command requests the provider key. It generates every local secret and creates bmas.yaml plus .env.
Select anthropic or openai if you use a different provider. Then open Mission Control at http://localhost:9321.
Read the Quick Start if this is your first installation.
The default stack runs on one host.
| Service | Purpose |
|---|---|
| Redis | Supplies locks, notifications, and live projections. |
| LiteLLM | Routes model requests through one API. |
| Starter agent | Executes runtime roles through LiteLLM. It does not provide tools. |
| Daemon | Runs tasks and benchmark attempts. It saves durable state in SQLite. |
| Mission Control | Shows tasks, benchmark data, runtime capacity, files, logs, costs, and operator actions. |
The optional GPU profile adds local triage through vLLM. The normal starter does not need a GPU or a separate edge node.
| Runtime | Coordination model | Default use |
|---|---|---|
| Classic | A control unit selects roles and reads a durable blackboard. | Adaptive work that needs critique and convergence. |
| Patchboard | Contributors work independently before one integration turn. | Parallel proposals and independent analyses. |
| Stigmergic workspace | Workers revise one shared artifact in a fixed order. | Iterative drafting and refinement. |
Each runtime uses stable activation identifiers and durable recovery checkpoints. Mission Control reads the same capability contracts that the daemon enforces.
| Command | Result |
|---|---|
./scripts/bmas init --provider gemini |
Creates a starter configuration and secure local secrets. |
./scripts/bmas up |
Builds the stack and waits for readiness. |
./scripts/bmas doctor |
Checks files, secrets, Compose, and live services. |
./scripts/bmas smoke |
Submits one task and waits for completion. |
./scripts/bmas dev |
Starts the development Compose override. |
./scripts/bmas test |
Runs the same checks as continuous integration. |
./scripts/bmas docs-check |
Checks documentation links. |
The Makefile provides matching targets, such as make up and make test.
Start with the guide that matches your work.
| Goal | Document |
|---|---|
| Install the starter | Quick Start |
| Understand the services | Concepts |
| Change models or runtime limits | Configuration |
| Deploy outside a local computer | Deployment |
| Operate and recover the stack | Operations |
| Change the source code | Development |
| Add Hermes execution nodes | Node Setup |
| Create and operate benchmarks | Benchmarking |
| Understand statistical reports | Benchmark Statistics |
| Compare runtime behavior | Runtime Variants |
| Read all documentation | Documentation index |
| Directory | Purpose |
|---|---|
daemon/ |
Python orchestration API and durable task state. |
agent/ |
Starter execution API and optional Hermes adapter. |
mission-control/ |
Next.js operator interface. |
litellm/ |
Model gateway configuration generator. |
redis/ |
Redis configuration. |
triage/ |
Optional local complexity classifier. |
eval/ |
Legacy command-line evaluation tools. |
examples/ |
Supported starter and homelab configurations. |
The classic runtime follows the blackboard multi-agent system described by Han and Zhang in Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture.
This project uses the GNU Affero General Public License v3.0.