AiHummer
English▾
Log in
v1.0.x▾
v1.0.xstable
{ }Swagger
Getting started/System Requirements

System Requirements

v1.0.x · updated 2026-07-05

AiHummer is a host-native product: it runs as a release tarball under systemd, so the requirements are deliberately small. The only hard dependency is a Linux host with PostgreSQL. Everything else — sidecars, a real model, a vector store — is optional and can be added later from the admin UI.

[!NOTE] AiHummer is host-native, not Docker. It deploys as a tarball running under systemd from ~/.aihummer (the home directory of the user who ran the installer). You do not need a container runtime, Kubernetes or any orchestrator.

Operating system

AiHummer runs on Linux only. There is no Windows or macOS server build — the gateway and its sidecars are packaged as per-architecture Linux artifacts and are deployed with systemd. (The client is a separate mobile & desktop app; that is a channel, not the server.)

  • A modern 64-bit Linux distribution with systemd.
  • x86_64 (amd64) or arm64 — the installer pulls the matching per-arch bundle.
  • sudo/root access is not strictly required: a normal install runs via sudo, but running the installer without root installs AiHummer in rootless mode under systemd --user — see Installation.

Database

PostgreSQL is the only hard dependency and the single source of truth for all state. The pgcrypto extension is required — it backs the encrypted credential vault. Without a database, the gateway starts in a reduced health-only mode and serves nothing useful.

[!IMPORTANT] Enable pgcrypto in the target database before first run:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

The gateway connects via a DSN in AIHUMMER_DATABASE_URL. For multitenant isolation you can additionally point AIHUMMER_DB_APP_URL at a restricted aihummer_app role to activate Postgres Row-Level Security; local installs set this up automatically. Database migrations are forward-safe and applied automatically under an advisory lock on the owner pool.

Hardware

These figures are guidance for a single-host deployment of the gateway plus PostgreSQL. Sidecars (STT/TTS, browser, vector store) add their own footprint and are usually placed on the same host only for small deployments.

Profile CPU RAM Disk Notes
Minimum (eval) 2 vCPU 2 GB 10 GB Gateway + Postgres, mock model, no sidecars
Recommended 4 vCPU 8 GB 40 GB SSD Gateway + Postgres + a couple of sidecars
Voice / local models 8+ vCPU (GPU optional) 16+ GB 80+ GB SSD STT/TTS, embedder, local LLM endpoint

Disk usage grows with conversation history, the media blob directory (AIHUMMER_BLOB_DIR), knowledge ingestion and audit retention. Plan PostgreSQL backups (pg_dump + WAL/PITR) accordingly.

Sidecars (optional)

Sidecars are separate HTTP services, each under its own systemd unit. The gateway reaches them by URL, so a sidecar can run on the same host, on another host, or you can point at an existing instance. They are all free/local and never required for a basic deployment.

Sidecar Default port Enables
STT (faster-whisper) 8001 Speech-to-text for voice turns
TTS (edge-tts) 8002 Text-to-speech for voice turns
Video (ffmpeg) 8005 Video understanding
SearXNG 8888 The web_search tool
Chrome/CDP 9222 The browser / computer tools

STT, TTS and video are installed out of the box by the installer (skip them with the AIHUMMER_SKIP_* variables). The semantic embedder is opt-in (--with-embedder): it pulls PyTorch (hundreds of MB), and without it memory falls back to lexical search. The other sidecars can be provisioned natively by the installer, or you can attach an existing one by URL — see Installation.

LLM providers

AiHummer never requires a paid model. It works out of the box on free/local models and a Codex/ChatGPT-subscription transport; per-tenant BYOK keys are strictly optional.

Supported providers:

  • Anthropic.
  • OpenAI.
  • Any OpenAI-API-standard endpoint — local model servers, OpenRouter, or Gemini’s OpenAI-compatible endpoint, for example.
  • Codex / ChatGPT-subscription transport — drive a model through a ChatGPT subscription rather than a billed API key.

[!TIP] If you start the gateway without a model wired (AIHUMMER_LLM_PROVIDER / AIHUMMER_LLM_MODEL / AIHUMMER_LLM_GATEWAY_URL), replies come from a deterministic mock so you can validate channels and routing before connecting a real model.

[!NOTE] AiHummer exposes only the OpenAI-compatible POST /v1/chat/completions endpoint. There is no /v1/models or /v1/embeddings HTTP endpoint, and observability is OTLP-push (no Prometheus /metrics).

Where to next