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

Then open http://localhost:8000/admin/login⁠ and sign in with changeme.

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 admin — /admin for users, brains, NeuronTypes, audit, license. Setup wizard guides Entra/Google config on first login.
• 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 (nomic-embed-text-v1.5, no third-party API) blended with keyword + 1-hop relationship ranking.
• Auth — Microsoft Entra ID (recommended), optional Google OAuth, admin-password fallback for first-run.

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

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

⁠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;
  

  Copy

• 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

⁠Optional but typical

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/admin/login⁠, sign in with changeme, and the in-app Configuration wizard will walk you through Entra/Google/license setup.

⁠Memory requirement

2 GB minimum. The container downloads a local embedding model (~270 MB) from Hugging Face on first start and uses it to vectorize neurons for semantic search. Anything below 2 GB will fail to load the model or crash under load. The compose snippet above includes mem_limit: 2g for that reason.

⁠Azure Container Apps quick deploy

The image is public, so no --registry-* flags are needed:

az group create -n rg-aiqbee-hive -l australiaeast

# Postgres Flexible Server (B1ms, ~$13/mo)
az postgres flexible-server create -g rg-aiqbee-hive -n aiqbee-hive-db \
  -l australiaeast -u aiqbeeadmin -p 'STRONG_DB_PW' \
  --sku-name Standard_B1ms --tier Burstable --storage-size 32 --version 16 --yes
az postgres flexible-server db create -g rg-aiqbee-hive \
  --server-name aiqbee-hive-db --database-name aiqbee_hive

# Container Apps
az extension add --name containerapp --upgrade
az containerapp env create -n aiqbee-hive-env -g rg-aiqbee-hive -l australiaeast

az containerapp create -n aiqbee-hive -g rg-aiqbee-hive \
  --environment aiqbee-hive-env \
  --image aiqbee/hive-server:master \
  --target-port 8000 --ingress external \
  --min-replicas 0 --max-replicas 1 --cpu 1.0 --memory 2Gi \
  --env-vars \
    DATABASE_URL="postgresql+asyncpg://aiqbeeadmin:[email protected]:5432/aiqbee_hive?ssl=require" \
    MCP_SERVER_BASE_URL="https://PLACEHOLDER" \
    ADMIN_PASSWORD="STRONG_ADMIN_PW"

# Read the assigned FQDN and update MCP_SERVER_BASE_URL
URL=$(az containerapp show -n aiqbee-hive -g rg-aiqbee-hive \
  --query "properties.configuration.ingress.fqdn" -o tsv)
az containerapp update -n aiqbee-hive -g rg-aiqbee-hive \
  --set-env-vars MCP_SERVER_BASE_URL="https://$URL"
echo "Open https://$URL/admin/login"

⁠Configure probes (recommended for production)

az containerapp create doesn't accept probes inline. After the app is up, configure them via the Azure portal: Container App → Containers → (your container) → Health probes → Add. Set:

• Readiness — HTTP, path /ready, port 8000, failure threshold 60, period 10s.
• Liveness — TCP, port 8000, period 30s.
• Startup — TCP, port 8000, failure threshold 30, period 5s.

Without these, a rolling deploy can route traffic to a new replica before alembic migrations finish — visible to end users as 502s during deploys, especially on large databases.

For App Service (Docker), Azure Marketplace one-click deploys, or full screenshots-and-text walkthroughs, request the customer documentation pack from [email protected]⁠.

⁠Kubernetes quick deploy

The image is public on Docker Hub — no imagePullSecrets needed. The manifests below are a working single-replica deployment with the recommended probe configuration baked in.

⁠1. Namespace + secrets

kubectl create namespace aiqbee-hive

kubectl create secret generic aiqbee-hive-secrets -n aiqbee-hive \
  --from-literal=DATABASE_URL='postgresql+asyncpg://USER:PASS@HOST:5432/aiqbee_hive?ssl=require' \
  --from-literal=ADMIN_PASSWORD='STRONG_ADMIN_PW' \
  --from-literal=MCP_SERVER_BASE_URL='https://hive.example.com'

⁠2. Deployment + Service

Save as aiqbee-hive.yaml and kubectl apply -f it:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aiqbee-hive
  namespace: aiqbee-hive
spec:
  replicas: 1
  selector:
    matchLabels: { app: aiqbee-hive }
  template:
    metadata:
      labels: { app: aiqbee-hive }
    spec:
      containers:
        - name: aiqbee-hive
          image: aiqbee/hive-server:master
          ports:
            - containerPort: 8000
          envFrom:
            - secretRef: { name: aiqbee-hive-secrets }
          # Liveness: TCP only — a transient DB outage shouldn't restart the pod.
          livenessProbe:
            tcpSocket: { port: 8000 }
            initialDelaySeconds: 15
            periodSeconds: 30
          # Readiness: HTTP /ready — gates traffic until alembic + init finish.
          readinessProbe:
            httpGet: { path: /ready, port: 8000 }
            initialDelaySeconds: 5
            periodSeconds: 10
            failureThreshold: 60   # ~10min budget for slow alembic on large DBs
          startupProbe:
            tcpSocket: { port: 8000 }
            periodSeconds: 5
            failureThreshold: 12
          resources:
            requests: { memory: "1Gi", cpu: "250m" }
            limits:   { memory: "2Gi", cpu: "1000m" }
          securityContext:
            allowPrivilegeEscalation: false
            capabilities: { drop: ["ALL"] }
---
apiVersion: v1
kind: Service
metadata:
  name: aiqbee-hive
  namespace: aiqbee-hive
spec:
  selector: { app: aiqbee-hive }
  ports:
    - port: 80
      targetPort: 8000

⁠3. Ingress (nginx example — adapt to your controller)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aiqbee-hive
  namespace: aiqbee-hive
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod   # if cert-manager installed
spec:
  ingressClassName: nginx
  tls:
    - hosts: [hive.example.com]
      secretName: aiqbee-hive-tls
  rules:
    - host: hive.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: aiqbee-hive
                port: { number: 80 }

For the Helm chart, multi-replica configuration (shared JWT_SECRET etc.), or PVC-backed /app/data storage, request the customer documentation pack from [email protected]⁠.

⁠Health endpoints — use these for probes

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 /admin/login with 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 with their Entra/Google account at /admin/login (or /). Their user record is created automatically on first sign-in.
4. Create a brain — any signed-in user clicks New Brain on the dashboard. Each brain is an isolated knowledge graph; typically one per team or project.
5. Connect an MCP client — open the brain's settings page and copy its MCP connection URL. 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:

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.

⁠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

Or configure it directly in ~/.codex/config.toml (equivalent, and the form the OpenAI docs specify):

[mcp_servers.aiqbee-hive]
url = "https://hive.example.com/brain/<brain-id>/mcp"
auth = "oauth"          # omit for a Hive that needs no sign-in

Then codex mcp list to confirm, and codex mcp login aiqbee-hive if the server requires OAuth. In Codex's TOML the transport is implied by the key: url means streamable HTTP, command means stdio.

⁠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

For 3rd-party agents, automation scripts, and external apps that need to manage which brains exist (rather than the contents of an existing brain), Hive ships a separate REST API at /api/v1:

• Create, get, edit, soft-delete, and list brains
• List available brain templates (and the NeuronTypes each brings)
• Service-account bearer-token auth (OAuth 2.0 client_credentials grant against /token); per-SA API permission flag controls who can use it
• Off by default — the operator turns it on from /admin/config and grants individual service accounts the permission

Once you've created a brain via the API, your MCP client connects to it just like any other brain. The two interfaces are complementary: REST for catalogue management, MCP for working inside a brain.

The full contract — endpoint shapes, request/response bodies, error envelopes — lives in the Swagger UI at /api/docs on a running server. This overview deliberately doesn't duplicate that detail; the spec at the deployment is always the source of truth.

⁠Licensing & registration

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

• Single user, zero setup. Out of the box you get 5 brains and 500 neurons per seat, pooled — enough for one person to evaluate or run a personal Hive, 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

• Customer documentation pack (Azure / K8s / Helm / Marketplace step-by-step guides as markdown) — request from [email protected]⁠.
• Security disclosures — email [email protected]⁠ directly.

⁠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 (1 brain × 1 user × 50 neurons), 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.