Hivemind

A self-hosted AI agent orchestration platform — an org chart of agents that plan, code, and review software together, powered entirely by local LLMs.

Agents build. You approve.

Why? · Features · Architecture · Quick Start · Configuration · Project Layout · License

---

Why?

Multi-agent coding setups usually mean API keys, per-token bills, and a pile of unstructured chat sessions. Real projects need more than one smart prompt: they need roles, delegation, review gates, and shared state.

Hivemind runs a whole software company on your own machine. Agents sit in an org chart (CEO → CTO → developers), pick up issues, work in isolated Docker sandboxes, commit to Git, and route decisions back to you through an approval workflow — all driven by local models through llama.cpp. No external AI APIs, your code and data never leave your network.

┌──────────┐   strategy    ┌──────────┐   tasks    ┌────────────────┐
│ CEO agent│ ────────────▶ │ CTO agent│ ─────────▶ │ developer      │
└──────────┘               └──────────┘            │ agents (sandbox│
     ▲                        ▲                    │ + git repos)   │
     │        approvals       │                    └────────────────┘
     └────────────────────────┴──────── 👤 you (web UI)

Features

• Autonomous agent engine — plan → act → verify loop with 17 built-in tools, MCP server integration, LSP-backed code analysis, loop detection, context compaction, LLM streaming, and full session event history.
• Org-chart delegation — CEO → CTO → developer hierarchy with automatic agent wake-up: heartbeat, event triggers, coalescing, deferring, recovery.
• Issue tracking — issues with checklists, comments, labels, and status-based workflows; agents pick up and resolve them.
• Projects & goals — mission / objective / task hierarchy, project-level lead agents, bare Git repo integration, and artifacts.
• Human approval gates — strategy approvals, code review, and user decisions route back to the web UI; agents pause and react automatically.
• Sandboxed execution — one isolated Docker container per agent with resource limits (512MB RAM, 1 CPU) and Git repos mounted at /workspace.
• Multi-company — create companies per purpose, assign agents from a shared pool, and configure each org chart independently.
• Agent memory — long-term memory backed by vector embeddings (OpenAI-compatible endpoint) with semantic search.
• Real-time UI — React PWA with WebSocket event streaming, installable and push-enabled via Workbox.
• Bring your own LLM — any llama.cpp (OpenAI-compatible) endpoint for generation and embeddings. Fully self-hosted, including embeddings.

Architecture

React PWA (Vite) ──── NestJS API (:15001, serves SPA + API)
                            │
                  ┌─────────┼───────────────┐
                  │         │               │
                Redis    PostgreSQL      MinIO
               (:15003)  (:15002,       (:15010)
                          pgvector)

Layer	Technology
Backend	NestJS 11, TypeScript, Node.js 22+
Database	PostgreSQL 16 + pgvector, Drizzle ORM (31 tables)
Event bus	Redis 7 (Pub/Sub)
Frontend	React 19, Vite 6, TailwindCSS v4, Radix UI, TanStack Query
Realtime	Socket.io (WebSocket)
LLM	llama.cpp (OpenAI-compatible API)
File storage	MinIO (S3-compatible)
Deployment	Docker Compose, pnpm workspaces monorepo

Backend modules

Module	Responsibility
Agent Engine	Agent loop execution, sessions, memory, planning
Orchestrator	Sandbox prep → prompt assembly → runner invocation
Wakeup	Heartbeats, event triggers, coalescing, deferring, recovery
Tool Registry	17 built-in tools, per-role permissions, MCP servers, LSP analysis
LLM	Endpoint CRUD, health checks, embeddings, streaming
Sandbox	Docker container lifecycle, per-agent isolation
Issues	Issue CRUD, comments, labels, checklists, status workflow
Goals	Mission / objective / task hierarchy
Approval	Approval workflow (pending → approved/rejected)
Bridge	Agent pool CRUD, session routing
Project	Project CRUD, lead agents, artifacts
Company	Companies, agent assignment, org charts
Git	Bare repo management, branch strategy, commits/merges
Code	Code analysis and manipulation (Gitea integration, PRs)
Storage	MinIO S3-compatible uploads/downloads
Monitor	Sandbox/session/wakeup monitoring, token usage
Collab	Discussion channels, consensus/votes, agent-to-agent messaging
Activity	Activity log
Health	DB / Redis / engine / LLM health checks
Settings	System settings, integration tests
WebSocket	Socket.io realtime event broadcast

Quick Start

Prerequisites: Node.js 22+, pnpm 10+, Docker + Docker Compose.

Development

# install dependencies
pnpm install

# start infrastructure (PostgreSQL + pgvector, Redis, MinIO)
docker compose up -d

# apply the DB schema
pnpm --filter @hivemind/api db:push

# run the API server (port 15001)
pnpm --filter @hivemind/api start:dev

# run the UI dev server (port 15017, proxies to the API)
pnpm --filter @hivemind/ui dev

Production (Docker Compose)

The API image is a multi-stage build that bundles the built UI, so a single stack serves everything:

# 1. build and start the full stack
docker compose up -d --build

# 2. first run: apply the DB schema
pnpm --filter @hivemind/api db:push

# 3. one-time: build the agent sandbox image
docker build -f docker/Dockerfile.sandbox -t hivemind-sandbox:latest docker/

# 4. follow the logs
docker compose logs -f

Open http://localhost:15001 — the API container mounts /var/run/docker.sock to manage sandbox containers on the host.

Manual build (without Docker for the app itself)

pnpm --filter @hivemind/shared build
pnpm --filter @hivemind/api build
pnpm --filter @hivemind/ui build
cd apps/api && node dist/main.js

Configuration

Everything is env-driven (see .env.example):

Variable	Default	Purpose
DATABASE_URL	postgresql://hivemind:hivemind@localhost:15002/hivemind	PostgreSQL connection string
REDIS_URL	redis://localhost:15003	Redis event bus
PORT	15001	API port (serves SPA + API)
EMBEDDING_URL	http://localhost:19998	OpenAI-compatible embedding endpoint
STORAGE_S3_ENDPOINT	http://localhost:15010	MinIO S3 endpoint
STORAGE_S3_BUCKET	hivemind-files	File storage bucket
STORAGE_S3_ACCESS_KEY / STORAGE_S3_SECRET_KEY	hivemind / hivemind123	MinIO credentials

Inside Docker Compose, services talk over the hivemind-net network (postgres:5432, redis:6379, minio:9000).

Ports

Service	Port
NestJS API (SPA + API)	15001
PostgreSQL	15002
Redis	15003
MinIO API (S3)	15010
MinIO Console	15011
Vite dev server	15017

Volumes

Volume	Purpose
hivemind_pgdata	PostgreSQL data
hivemind_redis_data	Redis persistence
hivemind_repos	Bare Git repos (/data/hivemind/repos/)
hivemind_minio_data	MinIO file storage

Project Layout

apps/
  api/                # NestJS backend
    src/modules/      # 20 domain modules (agent engine, orchestrator, sandbox, ...)
    src/database/     # Drizzle schema (31 tables) + migrations
    src/events/       # Redis event bus
    src/websocket/    # Socket.io gateway
    src/common/       # shared utils (prompt builder, pagination, ...)
  ui/                 # React PWA frontend
    src/pages/        # dashboard, projects, issues, agents, ...
    src/components/   # shared UI (layout, Radix wrappers)
    src/hooks/        # useApi, useSocket, useMediaQuery
    src/stores/       # global state
packages/
  shared/             # shared types, Zod schemas, constants
docker/
  Dockerfile.sandbox  # agent sandbox image (debian + node 22 + git + tools)
docker-compose.yml
docs/                 # architecture and development docs
skills/               # agent skill definitions

Contributing

Issues and pull requests are welcome.

License

MIT © ByungHyun21