Aiqbee Hive — self-hosted AI context management platform with MCP server, web UI, and PostgreSQL.
10K+
Self-hosted brain management platform with an MCP server, web admin UI, and PostgreSQL — runs as a single Docker container.
Use it to give your team a shared, governable knowledge graph that any MCP client (Claude Desktop, Claude Code, custom agents, ChatGPT) can read and write to. Single-tenant by design — one instance per organization, your infrastructure, your data.
The image is public — no docker login required.
docker run --rm -p 8000:8000 \
-v hive-data:/app/data \
-e DATABASE_URL="postgresql+asyncpg://user:pass@host:5432/aiqbee_hive" \
-e ADMIN_PASSWORD="changeme" \
-e MCP_SERVER_BASE_URL="http://localhost:8000" \
aiqbee/hive-server:master
Keep the
-v hive-data:/app/datavolume. It holdssetup.json— your Hive's stable instance id, and (once you register) your licence. With--rmand no volume every run starts a brand-new Hive identity. Your knowledge graph itself lives in Postgres, so it survives either way.
Then open http://localhost:8000/auth/login and sign in with email [email protected] and password changeme. (Set ADMIN_EMAIL to use a different address for this first administrator.)
If you don't have a Postgres instance handy, the Docker Compose recipe below stands one up alongside Hive.
aiqbee_search, aiqbee_fetch, aiqbee_create_neuron, …) over Streamable HTTP, with PKCE OAuth for Claude/ChatGPT clients./admin for users (invitations, roles, sign-in codes), groups, service accounts, brains, templates, email (SMTP) and licensing./api/v1/brains (create / list / get / edit / soft-delete) and /api/v1/brain-templates so external agents and apps can programmatically create and manage the brain catalogue without driving the web UI. Service-account bearer-token auth; off by default and enabled per-deployment from /admin/config. Curated Swagger UI at /api/docs — the full contract lives there rather than being duplicated in this overview.EMBEDDING_MODEL=english (nomic-embed-text-v1.5, the default) or international (snowflake-arctic-embed-m-v2.0, 70+ languages, needs more container memory). Both ship inside the image.ADMIN_EMAIL / ADMIN_PASSWORD. MCP clients sign in the same ways — email + password (plus the emailed code when it is on) or Microsoft/Google.The Docker Hub repo carries the distroless variant only — production-grade, ~80 MB compressed, runs as nonroot UID 65532, no shell. Pre-release and internal build variants are intentionally not published here and are not customer-facing.
| Tag | Use for |
|---|---|
latest | Always points at the newest released version. Good for docker run demos. |
master | Tracks the master branch — same as latest but explicit. |
X.Y.Z | Pinned release (e.g. 1.0.0 — note: no leading v). Also X.Y (e.g. 1.0) for the latest patch in a minor series. Recommended for production. |
<sha> | Per-commit immutable tag — e.g. 6ad5590. Use when you need exact reproducibility against a specific release commit. |
Both linux/amd64 and linux/arm64 are published as a single multi-arch manifest, so docker pull picks the right one automatically (works on Apple Silicon).
DATABASE_URL and ADMIN_PASSWORD must be supplied via environment variables (or your platform's container-secret mechanism — Compose, Container Apps, Kubernetes Secret, etc.). Without both, the container starts but every route serves a static instructions page at /setup until the operator restarts with the values set. Bootstrap config is intentionally not settable through the web UI: an unauthenticated visitor on a public-facing instance could otherwise race the legitimate operator and seize the admin account.
You need a running PostgreSQL 14 or later server that the container can reach over the network. Hive does not bundle a database — you supply one (managed service or self-hosted). The DSN you put in DATABASE_URL must point at:
An existing database — Hive does not run CREATE DATABASE on startup. Create the database before pointing Hive at it (aiqbee_hive is the convention used throughout these examples; any name works as long as it matches the database segment of your DATABASE_URL).
A user that has full DDL + DML on the database's public schema. Alembic migrations on startup create and alter tables, so the user needs CREATE, ALTER, DROP, REFERENCES, USAGE plus the usual SELECT/INSERT/UPDATE/DELETE. The simplest grant for a dedicated Hive user is to make them the database owner:
CREATE DATABASE aiqbee_hive;
CREATE USER hive WITH PASSWORD 'STRONG_DB_PASSWORD';
ALTER DATABASE aiqbee_hive OWNER TO hive;
SSL — almost always required by managed Postgres services (Azure Flexible Server, AWS RDS, Supabase, Neon). Append ?ssl=require to the DSN.
Network reachability — for managed services, allow the container's outbound IP / VNet through the Postgres firewall.
If you don't have a Postgres handy, the Docker Compose recipe below stands one up alongside Hive with the right permissions baked in.
| Variable | What it does |
|---|---|
DATABASE_URL | Async PostgreSQL DSN: postgresql+asyncpg://USER:PASSWORD@HOST:5432/aiqbee_hive. HOST is your Postgres server's hostname (a managed-service FQDN, the IP of a VM, or postgres if you run it as a sibling Compose service). 5432 is the PostgreSQL default port — change only if your DB listens elsewhere. Append ?ssl=require for managed Postgres. The user must have full DDL + DML on the database's public schema (see prerequisite above). |
ADMIN_PASSWORD | Initial password for the bootstrap administrator account (sign in at /auth/login). Hashed on startup; plaintext never persisted. Pick at least 16 random characters. You can change it later at /account. |
MCP_SERVER_BASE_URL | Public HTTPS URL the server is reached on (e.g. https://hive.acme.com). Used for OAuth callback URLs and MCP discovery. Defaults to http://localhost:8000. |
| Variable | Notes |
|---|---|
ADMIN_EMAIL | Email address of the bootstrap administrator account. Defaults to [email protected]. |
SMTP_HOST (+ SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_ADDRESS, SMTP_FROM_NAME) | Outbound email, used for user invitations, password resets and email sign-in codes. SMTP_PORT defaults to 587 and SMTP_SECURITY to starttls (or tls / none). Can also be set by an administrator at /admin/security, which takes precedence. Without SMTP, invitation links are shown to the admin to pass on by hand. |
LICENSE_KEY | Only for air-gapped / manually-licensed deployments — a key from [email protected]. Most deployments don't need it: the built-in free tier needs nothing, and free/Enterprise licensing is self-serve from /admin/config (see Licensing below). |
AZURE_AD_TENANT_ID, AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET | Microsoft Entra ID for SSO. Configure these or use the in-app Configuration wizard at /admin/setup. |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Optional — adds "Sign in with Google" alongside Entra. |
MCP_OAUTH_REDIRECT_HOSTS | Extra HTTPS hosts an MCP client may be returned to after signing in (comma-separated). Loopback addresses, the VS Code / Cursor / Windsurf / Claude app links, and claude.ai, claude.com, vscode.dev and chatgpt.com are allowed already; add a host only if a client's sign-in is refused with "an address this Hive doesn't recognise". |
LOG_LEVEL | INFO (default), DEBUG, WARNING, ERROR. |
EMBEDDING_MODEL | english (default) or international. Picks the local embedding model used for semantic search — see Language support below. Both models ship inside the image. Read only on a first-time setup; after neurons exist, change it from /admin/config instead. |
JWT_SECRET, STATE_SIGNING_KEY, SESSION_SECRET_KEY, PROXY_CLIENT_SECRET | Required when running multiple replicas behind a load balancer (so all replicas sign with the same key). Single-container deploys can leave these unset — auto-generated on first boot. |
For the full env-var reference, multi-replica notes, and deployment recipes, email [email protected] for the customer documentation pack (markdown bundle).
Save this as docker-compose.yml:
services:
hive:
image: aiqbee/hive-server:master
ports:
- "8000:8000"
environment:
DATABASE_URL: postgresql+asyncpg://hive:hive@postgres:5432/aiqbee_hive
MCP_SERVER_BASE_URL: http://localhost:8000
ADMIN_PASSWORD: changeme
volumes:
# Holds setup.json — the Hive's stable instance id and, once you
# register, its licence. Without it a replaced container starts as a
# brand-new Hive. The knowledge graph itself lives in Postgres.
- hive-data:/app/data
depends_on:
postgres:
condition: service_healthy
restart: unless-stopped
mem_limit: 2g
postgres:
image: postgres:16-alpine
environment:
POSTGRES_USER: hive
POSTGRES_PASSWORD: hive
POSTGRES_DB: aiqbee_hive
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U hive"]
interval: 5s
retries: 5
volumes:
pgdata:
hive-data:
Then:
docker compose up -d
Open http://localhost:8000/auth/login, sign in as [email protected] with changeme, and the in-app Configuration wizard will walk you through Entra/Google/license setup.
Depends on which embedding model you run — the model is resident in memory and vectorizes neurons for semantic search.
EMBEDDING_MODEL | Minimum container memory |
|---|---|
english (default) | 2 GB |
international | 4 GB |
Below the minimum, the model fails to load or the container crashes under
search load. The compose snippet above sets mem_limit: 2g; raise it to
4g if you set EMBEDDING_MODEL=international, and remember to raise it on
your orchestrator too (Container Apps --memory, Kubernetes
resources.limits.memory) before switching.
Both models are baked into the image, so nothing is downloaded at runtime — including when you switch between them.
Semantic search quality depends on the embedding model, and the two ship with very different language coverage.
english (default) | international | |
|---|---|---|
| Model | nomic-embed-text-v1.5 | snowflake-arctic-embed-m-v2.0 |
| Languages | English | 70+, including German, French, Spanish, Portuguese, Japanese |
| Container memory | 2 GB | 4 GB |
If your neurons are not in English, choose international. The English
model does not merely score non-English content lower — its tokenizer strips
accents, so schön and schon become the same token, and long non-English
content consumes roughly twice the token budget per character. Nothing errors;
results are just quietly worse.
Set it at first install:
-e EMBEDDING_MODEL=international
Already running? Don't change the environment variable — it is only read when a Hive is first set up, and is ignored afterwards (the admin Configuration page will tell you so). Switching models re-processes every neuron, so it is a deliberate action from Configuration → Embedding model in the admin UI, which shows you the scope and a time estimate first. While the re-processing runs, neurons not yet re-processed are found by keyword search only — results stay correct, just temporarily narrower.
Deploy aiqbee/hive-server:master as a Container App with external ingress on port 8000, at least 2 GiB memory, the env vars above (secrets for DATABASE_URL and ADMIN_PASSWORD), and an Azure Database for PostgreSQL Flexible Server. Set MCP_SERVER_BASE_URL to the app's https:// FQDN, use /ready for the readiness probe and TCP 8000 for liveness (see Health endpoints), then open https://<fqdn>/auth/login. Step-by-step az commands are in the customer documentation pack.
The image is public — no imagePullSecrets needed. Run a single replica with the env vars above in a Secret, /app/data on a PVC, readiness probe on /ready, liveness on TCP 8000 (see Health endpoints), and an ingress terminating TLS. The Helm chart and ready-to-apply manifests (including multi-replica settings such as a shared JWT_SECRET) are in the customer documentation pack — request it from [email protected].
| Endpoint | Behaviour |
|---|---|
/health | Returns 200 once the process is alive; body reports DB + license status. A transient DB outage returns 503 — don't use this for liveness, or you'll restart the pod every time the DB blips. |
/ready | Returns 200 only after background init (alembic migrations + license init) finishes. Use this as the readiness probe. Returns 503 with {"status":"initializing"} until ready. |
TCP :8000 | Use this as the liveness probe — port-open is enough to prove the process is alive. |
Recommended Kubernetes probe block (matches the Deployment manifest under Kubernetes quick deploy):
startupProbe:
tcpSocket:
port: 8000
periodSeconds: 5
failureThreshold: 12
livenessProbe:
tcpSocket:
port: 8000
initialDelaySeconds: 15
periodSeconds: 30
readinessProbe:
httpGet:
path: /ready
port: 8000
initialDelaySeconds: 5
periodSeconds: 10
failureThreshold: 60
For Azure Container Apps: set the Readiness probe to HTTP /ready and Liveness probe to TCP/8000 in the Container App's "Health probes" panel.
/auth/login with the admin email (ADMIN_EMAIL, default [email protected]) and the ADMIN_PASSWORD you set./admin/config and set up Microsoft Entra ID and/or Google OAuth via the in-app form. (Bootstrap config — DATABASE_URL, ADMIN_PASSWORD — is env-var-only by design; everything else is configured here.)/auth/login with their Entra/Google account (their user record is created automatically on first sign-in), or with email + password if you invite them from /admin/users. Users can turn on email-code two-step sign-in at /account; admins can require it for everyone at /admin/security (needs SMTP)./connect) for step-by-step client config, or copy the MCP connection URL from the brain's page. Paste that URL into Claude Desktop, Claude Code, ChatGPT, or any MCP-compatible client; the URL handles OAuth-PKCE for you. For the CLI agents, see the one-liners below.Hive speaks streamable HTTP MCP. Two endpoints:
| Endpoint | Use |
|---|---|
/brain/{brain_id}/mcp | A specific brain — copy from the brain's page or /connect. Preferred. |
/mcp | Global endpoint, kept for backwards compatibility |
The examples below use the brain-specific endpoint against a locally-run
Hive — that's the URL step 5 tells you to copy. For a hosted Hive, substitute
https://hive.example.com for http://localhost:8000.
Use
https://for any Hive that isn't on your own machine.http://is fine forlocalhostonly, where traffic never leaves the loopback interface. On a remote Hive, plain HTTP would put OAuth tokens and your brain's contents on the wire in the clear.
claude mcp add --transport http aiqbee-hive \n http://localhost:8000/brain/<brain-id>/mcp
Scope defaults to local (this project only). Use --scope user to make it
available in every project, or --scope project to write a .mcp.json your
team shares via git. Then:
claude mcp list # confirm it registered
claude mcp login aiqbee-hive # OAuth, if your Hive requires sign-in
claude mcp remove aiqbee-hive # undo
OAuth-PKCE is handled for you — you can also run /mcp inside a Claude Code
session to authenticate interactively.
For a team-shared, version-controlled setup, commit .mcp.json:
{
"mcpServers": {
"aiqbee-hive": {
"type": "http",
"url": "https://hive.example.com/brain/<brain-id>/mcp"
}
}
}
codex mcp add aiqbee-hive --url http://localhost:8000/brain/<brain-id>/mcp
Then codex mcp login aiqbee-hive if the server requires OAuth.
Once an MCP client is connected, drive the brain in plain English from your LLM. Examples that just work:
<topic>"[email protected] read+write access to this brain" (admins only)[email protected]"Hive exposes 30+ MCP tools (create / update / delete / search / fetch on neurons, synapses, NeuronTypes, plus access management and audit). The LLM picks the right tool from your request — you don't need to know the tool names.
/api/v1 lets external agents and apps create, list, edit and soft-delete brains and list templates, authenticated as a service account (OAuth client_credentials against /token). It is off by default — enable it and grant individual service accounts the permission at /admin/config. The full contract is in the Swagger UI at /api/docs on a running server.
Database migrations run automatically on start. What changes for an existing Hive:
/admin/login redirects to /auth/login). On first start the Hive creates an administrator account for ADMIN_EMAIL (default [email protected]) using your existing ADMIN_PASSWORD — sign in with that (or just admin), then promote your own SSO account or invite colleagues at /admin/users. After that, ADMIN_PASSWORD is no longer read — change passwords at /account. Locked out? Set a new ADMIN_PASSWORD plus ADMIN_PASSWORD_RESET=true, restart once, then remove the flag./account; an admin can require them for everyone at /admin/security once SMTP is configured and a test email succeeds.MCP_OAUTH_REDIRECT_HOSTS.Aiqbee Hive is free to run — no payment and no Aiqbee account required:
/admin/config, enter your email and click Get Free Licence — it activates instantly, no setup. Same per-seat rates (5 brains + 500 neurons per user), pooled across the team, so 20 users share up to 100 brains and 10,000 neurons./admin/config → Purchase Enterprise Seats, and change seats or cancel any time via Manage / Cancel subscription.LICENSE_KEY).Limits are a pooled ceiling: total brains ≤ brains-per-seat × users, and total neurons ≤ neurons-per-seat × users, counted across all brains.
Aiqbee Hive is proprietary commercial software, not open source. By downloading and using this image you accept the Aiqbee Hive End User License Agreement. The binding text is the file bundled in the image you downloaded — read it with:
docker run --rm --entrypoint cat aiqbee/hive-server:master /app/LICENSE
(For an immutable pin, swap :master for the per-commit SHA tag of the build you pulled — e.g. :49249fa — or, once a versioned release is cut, the semver tag like :1.0.0. Either pins the LICENSE to exactly the bytes that shipped with that build; :master floats forward as new versions are released.) Headlines:
Copyright © 2024–2026 Aiqbee Limited. All rights reserved. Governed by New Zealand law.
Content type
Image
Digest
sha256:b67600b92…
Size
459.3 MB
Last updated
11 days ago
docker pull aiqbee/hive-server