Sign inSign up
hive-server logo

aiqbee/hive-server

By aiqbee

•Updated 11 days ago

Aiqbee Hive — self-hosted AI context management platform with MCP server, web UI, and PostgreSQL.

Image
Machine learning & AI
Developer tools
Databases & storage
1

10K+

aiqbee/hive-server repository overview

⁠Aiqbee Hive

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.

⁠Quick start (60 seconds)

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/data volume. It holds setup.json — your Hive's stable instance id, and (once you register) your licence. With --rm and 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.

⁠What you get out of the box

  • Free, pooled per-seat — 5 brains + 500 neurons per user, pooled across your team. Runs single-user with zero setup; register a free licence (just an email) for up to 20 users. No license key, no payment. Higher Enterprise limits available.
  • MCP server — 30+ tools (aiqbee_search, aiqbee_fetch, aiqbee_create_neuron, …) over Streamable HTTP, with PKCE OAuth for Claude/ChatGPT clients.
  • Web app — Home overview, an interactive graph explorer for every brain, an agent & team activity feed, an access & roles matrix that explains who can reach what, a Connect an agent wizard with copy-paste client config, and a Ctrl/⌘K command palette. Works on phone, tablet and desktop. Available in English, German, French and Spanish — switch with the flag button in the top bar; the language is picked from your browser by default.
  • Administration — /admin for users (invitations, roles, sign-in codes), groups, service accounts, brains, templates, email (SMTP) and licensing.
  • Management REST API — /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.
  • Hybrid search — local embeddings (no third-party API) blended with keyword + 1-hop relationship ranking. Choose 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.
  • Auth — Microsoft Entra ID (recommended), optional Google OAuth, and email + password sign-in for local accounts (created by admin invitation, with optional email-code two-step sign-in). The first administrator is a local account created from ADMIN_EMAIL / ADMIN_PASSWORD. MCP clients sign in the same ways — email + password (plus the emailed code when it is on) or Microsoft/Google.

⁠Image variants and tags

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.

TagUse for
latestAlways points at the newest released version. Good for docker run demos.
masterTracks the master branch — same as latest but explicit.
X.Y.ZPinned 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).

⁠Required configuration

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.

⁠Database prerequisite

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.

⁠Environment variables
VariableWhat it does
DATABASE_URLAsync 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_PASSWORDInitial 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_URLPublic 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.
⁠Optional but typical
VariableNotes
ADMIN_EMAILEmail 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_KEYOnly 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_SECRETMicrosoft Entra ID for SSO. Configure these or use the in-app Configuration wizard at /admin/setup.
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETOptional — adds "Sign in with Google" alongside Entra.
MCP_OAUTH_REDIRECT_HOSTSExtra 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_LEVELINFO (default), DEBUG, WARNING, ERROR.
EMBEDDING_MODELenglish (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_SECRETRequired 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).

⁠Docker Compose (app + Postgres in one go)

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.

⁠Memory requirement

Depends on which embedding model you run — the model is resident in memory and vectorizes neurons for semantic search.

EMBEDDING_MODELMinimum container memory
english (default)2 GB
international4 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.

⁠Language support

Semantic search quality depends on the embedding model, and the two ship with very different language coverage.

english (default)international
Modelnomic-embed-text-v1.5snowflake-arctic-embed-m-v2.0
LanguagesEnglish70+, including German, French, Spanish, Portuguese, Japanese
Container memory2 GB4 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.

⁠Azure Container Apps

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.

⁠Kubernetes

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]⁠.

⁠Health endpoints — use these for probes

EndpointBehaviour
/healthReturns 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.
/readyReturns 200 only after background init (alembic migrations + license init) finishes. Use this as the readiness probe. Returns 503 with {"status":"initializing"} until ready.
TCP :8000Use 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.

⁠After install — getting your team productive

  1. Sign in at /auth/login with the admin email (ADMIN_EMAIL, default [email protected]) and the ADMIN_PASSWORD you set.
  2. Configure SSO — go to /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.)
  3. Your team signs in at /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).
  4. Create a brain — any signed-in user clicks New brain on Home. Each brain is an isolated knowledge graph; typically one per team or project.
  5. Connect an MCP client — open Connect an agent (/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.
⁠Connecting a CLI coding agent

Hive speaks streamable HTTP MCP. Two endpoints:

EndpointUse
/brain/{brain_id}/mcpA specific brain — copy from the brain's page or /connect. Preferred.
/mcpGlobal 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 for localhost only, 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 Code
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"
    }
  }
}
⁠OpenAI Codex CLI
codex mcp add aiqbee-hive --url http://localhost:8000/brain/<brain-id>/mcp

Then codex mcp login aiqbee-hive if the server requires OAuth.

⁠Talking to the brain

Once an MCP client is connected, drive the brain in plain English from your LLM. Examples that just work:

  • "Add this to the brain: …"
  • "Search the brain for what we know about <topic>"
  • "Prompt me to store lessons learned in the brain whenever you spot one"
  • "Optimize the brain — flag duplicates, suggest a better NeuronType structure"
  • "Grant [email protected] read+write access to this brain" (admins only)
  • "Revoke access for [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.

⁠Programmatic brain management for agents and apps

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

⁠Upgrading from an earlier version

Database migrations run automatically on start. What changes for an existing Hive:

  • Administrators are now user accounts. The shared admin password page is gone (/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.
  • The web UI is now translated into German, French and Spanish. The language follows each browser's preference (English otherwise) and can be changed with the flag button; nothing to configure. MCP sign-in pages stay English.
  • Back up your database before upgrading. Migrations are additive, but an older image will not start against the upgraded database, so rolling back means restoring the backup.
  • Everyone signs in once more after the upgrade; existing web sessions end. MCP connections and service accounts keep working.
  • Email sign-in codes start off for every account. Users opt in at /account; an admin can require them for everyone at /admin/security once SMTP is configured and a test email succeeds.
  • MCP sign-in shows a choice of Microsoft/Google or email + password, and only returns to recognised client addresses — clients hosted elsewhere (e.g. Copilot Studio, Postman, n8n) need their callback host in MCP_OAUTH_REDIRECT_HOSTS.
  • SSO accounts are matched by identity, not email alone. A Microsoft or Google sign-in only attaches to an existing account with the same email when the provider verifies that email, and never to a password or administrator account.

⁠Licensing & registration

Aiqbee Hive is free to run — no payment and no Aiqbee account required:

  • Two seats, zero setup. Out of the box you get 2 seats (one human user + one service account) with 5 brains and 500 neurons per seat, pooled — enough to run the full loop, human curates in the UI and an AI tool queries over MCP, with no license key required.
  • Free registration — up to 20 users. On /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.
  • Enterprise (paid, per-seat). Higher pooled limits — 10 brains and 2,000 neurons per seat — for 21+ users. Buy seats from /admin/config → Purchase Enterprise Seats, and change seats or cancel any time via Manage / Cancel subscription.
  • Custom / air-gapped. For bespoke limits, or Hives with no outbound connectivity, email [email protected]⁠ for a manually-issued key (set via LICENSE_KEY).

Limits are a pooled ceiling: total brains ≤ brains-per-seat × users, and total neurons ≤ neurons-per-seat × users, counted across all brains.

⁠Support

⁠What this image is not

  • Not a SaaS-managed instance. You run it on your infrastructure; Aiqbee has no remote access to your deployment, no telemetry hook into your data, and no path to your PostgreSQL.
  • Not multi-tenant. Each Hive instance is one organization's brain catalog. Stand up additional containers + databases for additional tenants.

⁠License (in short)

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:

  • Free for your organization's internal use within the free-tier limits (2 seats, pooled 5 brains + 500 neurons per seat), or within the limits in your paid license key. No payment is required to evaluate or run the free tier.
  • No redistribution, no resale, no rebranding, no reverse engineering, no derivative works. The Cython-compiled binary, the schema, the MCP tool surface, the embedding pipeline, and the Aiqbee/Hive trademarks are Aiqbee intellectual property.
  • You own your data. Aiqbee has no remote access to your deployment and never sees the data you put into Hive. The license covers the software, not the content.
  • No warranty — provided "as is". You decide whether it's right for your environment. Liability is capped per the EULA.
  • For higher limits, custom commercial terms, or a hosted-service licence, email [email protected]⁠.

Copyright © 2024–2026 Aiqbee Limited. All rights reserved. Governed by New Zealand law.

Tag summary

Content type

Image

Digest

sha256:b67600b92…

Size

459.3 MB

Last updated

11 days ago

docker pull aiqbee/hive-server