# 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.

### The starter pack

`deps.edn` ships the bare core: memory, KG edges, session ritual, swarm protocols, no
vessel, no code tool, no persistent KG driver. `starter.deps.edn` at the repo root is the
FOSS addon set that turns it into a working harness. `bin/hive-mcp-foss` merges it through
`-Sdeps` at boot, the same seam `bin/hive-mcp` uses for a personal `local.deps.edn`, so the
core's own `deps.edn` never names a backend.

| Role | Addon | Licence | Needs on the host | Status |
|---|---|---|---|---|
| Vessel (where lings run) | hive-emacs | MIT | an Emacs daemon | shipped |
| Knowledge graph store | hive-datahike (core default `:kg-backend`) | MIT | nothing, embedded | shipped |
| Vessel, headless | hive-tmux | MIT | tmux, Python 3 with libtmux | pending: IAddon constructor |
| Harness bridge | hive-claude | EPL-2.0 | Claude Code | pending: release with manifest |
| Code intelligence | lsp-mcp, clj-kondo-mcp, scc-mcp, basic-tools-mcp | MIT | clojure-lsp, clj-kondo, scc | pending: release with manifest |

The host discovers an addon only through its `META-INF/hive-addons` manifest. Every
shipped row was measured to mount or load in a cold boot; the pending rows sit commented
in `starter.deps.edn` with their coordinates and move up as each addon's release carries
its manifest. A host tool that is missing degrades that one addon with a logged reason;
the boot still completes. Swap hive-datahike for hive-datalevin by editing the file and
setting `:kg-backend :datalevin` in `.hive-project.edn`.

## One command

```bash
curl -fsSL https://hive-mcp.com/install.sh | sh -s -- --setup
```

That installs the `hive` CLI, writes the setup skills into `~/.claude/skills`,
clones the host, starts the services, installs bb-mcp at
`~/.local/share/hive-mcp/bb-mcp` and registers `hive` with your MCP clients through
`bb-mcp setup`. Drop
`--setup` to stop after the CLI and the skills, and let Claude Code drive the
rest: start it and say *"help me set up a FOSS build of the hive-mcp harness"*.

Every download is checked against a signed manifest first; see
[[Verifying-The-Install]].

### Or clone it yourself

```bash
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.

That is the backend. Clients do not launch it; they launch bb-mcp, which talks to it
over nREPL. Point your MCP clients at it through bb-mcp:

```bash
git clone https://github.com/hive-agi/bb-mcp
bb-mcp/bb-mcp setup            # publishes ~/.local/share/hive-mcp/bb-mcp, registers hive
bb-mcp/bb-mcp setup --check    # verify
```

Wherever bb-mcp is checked out becomes the reference. See [[Installation]] for the
flags and a manual JSON entry.

### 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_STARTER=0` | off | boot the bare core without `starter.deps.edn` |
| `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

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

# 2. embeddings
ollama pull nomic-embed-text

# 3. the host, with the starter pack (drop -Sdeps for the bare core)
clojure -Sdeps "$(cat starter.deps.edn)" -M:dev:nrepl
```

The same starter pack is baked into the container image: `docker build -t hive-mcp .`
then `docker run -p 7910:7910 -e HIVE_PROFILE=k8s-headless hive-mcp`. The image runs the
server from source; `--build-arg DEPS_OVERLAY=` builds the bare core.

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:

```clojure
;; ~/.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 (hive-claude: EPL-2.0) | the starter pack above, plus bb-mcp and 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.