Hive

Open-source MCP server for collaborative AI agents.

Status: v0.1 — under active development. Not yet released.

Hive is a self-hostable Model Context Protocol (MCP) server that gives teams of AI agents a shared mailbox, an identity model, and a notification fabric.

Stack

• Runtime: Node.js 20 LTS (see .nvmrc)
• Language: TypeScript (strict)
• Database: SQLite (default, via CLI — zero infra) or PostgreSQL 16+ (opt-in, for Docker / production deploys)
• Persistence layer: Kysely (type-safe SQL, multi-dialect) + better-sqlite3 (default) or pg (opt-in)
• MCP transport: @modelcontextprotocol/sdk over Streamable HTTP, hosted by fastify. Full 8-tool catalog ships in v0.1: get_agent_config, send_message, reply_to, read_mailbox, mark_read, check_unread_messages, list_agents, get_agent_status.
• CLI framework: commander (subcommand tree) + yaml (output) + chalk (terminal palette, single source in output/colors.ts per ADR-021) for hivectl. Migrations via Kysely.Migrator (portable SQLite/PG).
• Containerization: Docker + Docker Compose, optional — only needed for Postgres-backed deploys
• Package manager: pnpm 10 (see packageManager field)

Repository layout

This is a pnpm workspaces mono-repo:

packages/
├── server/    # MCP server, domain logic, persistence
├── cli/       # hivectl — admin CLI
├── client/    # reusable client library
└── shared/    # shared types and constants
deployment/    # Docker Compose + reference config (PRY-008)
docs/          # public documentation

Quick start

# Install the self-contained binary (no Node runtime required at the install host).
npm install -g @hivemine/hivectl

# 1. Bootstrap a fresh Hive (one-time). SQLite at ./var/db/hive.sqlite by default.
hivectl init --admin-email you@example.com --output-credential admin.jwt

# 2. Run the MCP server in the foreground (blocks until SIGINT/SIGTERM).
hivectl serve
# → Listening on http://127.0.0.1:8443/mcp

# Endpoints: POST/GET/DELETE /mcp, GET /healthz, GET /readyz, GET /.well-known/jwks.json
# See docs/mcp-server.md for the full operator guide.

For OS-supervised deployments (systemd on Linux, launchd on macOS) use hivectl service install instead of hivectl serve. Common admin operations:

hivectl hivekeeper create --email teammate@example.com --emit-credential
hivectl agent create --owner you@example.com --name worker-a --type worker --emit-credential
hivectl credential rotate worker-a@you.test-hive:latest --yes
hivectl audit query --limit 20

Full operator surface (10 subcommand groups: init / migrate / serve / service / config / hive / hivekeeper / agent / credential / audit) is documented in docs/hivectl.md.

Distribution

Hive is OSS (Apache 2.0). The release pipeline ships hivectl as a self-contained SEA binary (~108 MB, no Node runtime needed at the install host) under npm install -g @hivemine/hivectl, with per-platform packages for linux-x64, linux-arm64, darwin-arm64. Releases are cut via the release.yml workflow in this repo.

Intel Mac (darwin-x64) note for v0.1.0. Apple Silicon Macs (M1/M2/M3+) are supported via the darwin-arm64 binary. Intel Macs do not have a native binary in v0.1.0 — install Rosetta 2 (softwareupdate --install-rosetta on macOS 15+; macOS 11-14 prompts automatically on first need) and use the linux-x64 binary. The npm wrapper's install.js emits an actionable warning when it detects darwin x64. See CHANGELOG.md under [Unreleased]/Changed for the GitHub Actions runner rationale and the reversibility plan.

Deploy paths

Per ADR-008 the deploy story bifurcates into two topologies:

• Topology 1 — CLI + SQLite (default). npm install -g @hivemine/hivectl + hivectl init → SQLite at /var/lib/hive/hive.sqlite (Linux) or ~/Library/Application Support/Hive/hive.sqlite (macOS). Zero infra. Process supervised by hivectl service install (systemd on Linux, launchd on macOS). Documented in packages/cli/README.md and docs/hivectl.md.
• Topology 2 — Docker Compose (Postgres-backed). docker compose -f deployment/docker-compose.yml up -d against the bundled image. SQLite-in-volume by default; activate --profile postgres to add the Postgres service. Full operator guide in deployment/README.md.

PostgreSQL support ships in v0.1.0 (the persistence layer is multi-dialect from day one), but is officially validated end-to-end in CI starting v0.1.1.

Building from source (contributors)

If you are hacking on Hive itself rather than running it, see packages/cli/README.md for the dev-mode flow (pnpm install && pnpm build + node packages/cli/dist/main.js <args>) and the SEA build pipeline (pnpm --filter @hive/cli sea:build:darwin | sea:build:linux). CONTRIBUTING.md covers the PR workflow, commit conventions, and lint hooks.

Documentation

User-facing component documentation lives in docs/. Each package also has its own README:

• @hive/server — auth + persistence + domain logic.
• @hive/cli — hivectl admin CLI.
• @hive/client — reusable client library.
• @hive/shared — cross-package types.

Architecture decisions, tech specs, and product specs live in the vault, not in this repo.

Contributing

See CONTRIBUTING.md for development setup, commit conventions, and the PR workflow.

License

Apache License 2.0. See NOTICE for attributions.