FOSS Quickstart

FOSS Quickstart — batteries included

Status: Stable See also: Installation | Infrastructure-Setup | Core-Engine | Agents-and-Skills

Everything on this page is open source and runs on one machine. No private registry, no VPN, no credential store, no cloud account. The private addons add intelligence on top of this stack — they do not replace any of it.

What you get

Service	Port	Role	Required?
hive-mcp	7910	the host itself, over nREPL	yes
Chroma	8000	vector store behind memory + semantic search	yes — the default :memory-store backend
Ollama	11434	local embeddings, local models	strongly recommended
clojure-lsp sidecar	—	code intelligence for Clojure projects	optional
NATS	4222	event bus for hivemind / swarm	optional, off by default
Prometheus · Grafana · Loki	9090 · 3000 · 3100	observability	optional

Without Ollama the system still runs: memory stores and retrieves by tag, type and scope — only semantic search goes dark. That degradation is deliberate, and it's the same noop-fallback pattern the whole addon architecture uses.

One command

git clone https://github.com/hive-agi/hive-mcp
cd hive-mcp
bin/hive-mcp-foss

bin/hive-mcp-foss starts the FOSS services, waits until each is actually reachable (compose reporting a container as running is not the same as its process accepting connections), then execs the nREPL.

Then point your MCP client at it:

claude mcp add hive -- /path/to/hive-mcp/bin/hive-mcp-foss

Knobs

Variable	Default	Effect
HIVE_NATS=1	off	also start NATS (set :nats :enabled true in config too)
HIVE_TELEMETRY=1	off	also start Prometheus, Grafana, Loki, promtail
HIVE_SKIP_COMPOSE=1	off	services already run elsewhere — just wait and boot
HIVE_NREPL_PORT	7910	nREPL port
CHROMA_HOST / CHROMA_PORT	localhost / 8000	point at a remote Chroma
OLLAMA_HOST	http://localhost:11434	point at a remote Ollama
WAIT_TIMEOUT	90	seconds to wait per service

Doing it by hand

# 1. services
docker compose up -d chroma lsp-sidecar

# 2. embeddings
ollama pull nomic-embed-text

# 3. the host
clojure -M:dev:nrepl

Check Chroma is alive: curl http://localhost:8000/api/v2/heartbeat.

Configuration

The defaults are already the FOSS stack — {:services {:memory-store {:backend :chroma}}} ships as the built-in default, so an empty config works. Override only what you move:

;; ~/.config/hive-mcp/config.edn
{:services
 {:memory-store {:backend :chroma}
  :nats         {:enabled true :url "nats://localhost:4222"}}}

Secrets are read from the environment, never committed. If you add hosted models later, their keys live under :secrets — resolved from env vars at read time.

Your first session

The two rituals are plain requests, not slash commands — the model reaches for the project, memory, kg and kanban tools itself.

Start of a session:

hive project workflow catchup using pwd as dir

End of a session:

make memories on all learnings this session, kg connect them, sync kanban, and workflow wrap

Between those, multi batches whole sequences into a single call — see the DSL verbs in Tools-Reference.

Where the FOSS boundary sits

Layer	Licence	What it is
hive-mcp	AGPL-3.0	the host — protocols, registries, orchestrators, server, memory CRUD, KG edges, swarm, session ritual
FOSS addons	MIT	lsp-mcp, basic-tools-mcp, clj-kondo-mcp, hive-connectors, bb-mcp, olympus-web-ui
Product addons	Proprietary	ranking, learning, emergence detection, domain intelligence

Core ships a working noop default for every extension point, which is what makes the FOSS stack a complete system rather than a demo. Adding a private addon later changes no configuration you wrote here — it registers into seams that are already there.

Want to build your own addon into those seams? Creating-Addons scaffolds one in a single command.