AiHummer
English▾
Sign inAccount
v1.1.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Architecture/Sidecars

Sidecars

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

Some capabilities — speech, video, web search, a headless browser — are not part of the gateway itself. They run as sidecars: small, independent HTTP services that the gateway reaches by URL. Every sidecar is free and local: there is no mandatory paid API behind any of them.

What a sidecar is

A sidecar is a separate process exposing an HTTP API. The gateway never links it in or runs it in-process — it simply calls the URL you configure. Each sidecar

  • runs under its own systemd unit (host-native, no containers),
  • is wired to the gateway through an environment variable, and
  • can be installed natively next to the gateway, or pointed at an existing instance you already run elsewhere.

Because the contract is just HTTP, the same configuration works whether the sidecar is on localhost or on another host.

[!NOTE] Sidecars are optional — with one exception: web search (SearXNG) and the anti-detect browser (CloakBrowser) are installed out of the box. Their payloads ship inside the signed installer bundle and are installed offline. Turn them off with the installer flags --no-search and --no-browser. Every other capability is active only when its URL is configured; a minimal install is still just the gateway plus PostgreSQL.

The sidecars and their ports

Port Sidecar Backed by Powers Wired with
8001 STT faster-whisper speech-to-text AIHUMMER_STT_URL
8002 TTS edge-tts text-to-speech AIHUMMER_TTS_URL
8005 video ffmpeg video understanding AIHUMMER_VIDEO_URL
8888 SearXNG SearXNG the web_search tool installed by the installer, setting hidden; external instance — --external-search=URL
9222 Chrome / CDP Chrome (CDP) the browser tool installed by the installer, setting hidden; external instance — --external-browser=URL

The voice sidecars are the out-of-the-box path: STT (:8001) feeds the agent turn and TTS (:8002) speaks the answer, both on free/local engines. Video understanding (:8005) is an additional, opt-in sidecar. SearXNG (:8888) backs web_search, and a Chrome/CDP endpoint (:9222) backs the browser tool.

Wiring sidecars

You point the gateway at each sidecar with the matching catalog setting — from the admin UI (Management → Settings) or with aihummer settings set. gateway.env is bootstrap-only and is ignored for these keys. For the host-native install the voice sidecars (STT/TTS) are configured for you; web search and the browser are wired by the installer itself — you never set their addresses and they are not shown in the settings; the rest you enable as needed.

# Voice in/out (auto-configured by the installer for STT/TTS)
aihummer settings set AIHUMMER_STT_URL http://127.0.0.1:8001
aihummer settings set AIHUMMER_TTS_URL http://127.0.0.1:8002

# Optional video sidecar
aihummer settings set AIHUMMER_VIDEO_URL http://127.0.0.1:8005

[!TIP] Because each sidecar is just a URL, you can centralise heavy services. Point several gateways at one shared STT/TTS instance instead of running a copy per host; for search and the browser the installer flags --external-search=URL and --external-browser=URL do the same.

Running them natively or shared

Each sidecar lives under its own systemd unit on the host, so you operate it like any other service — start, stop and read logs independently of the gateway. If you already run, say, a SearXNG or a Chrome/CDP endpoint, pass the installer --external-search=URL or --external-browser=URL: no local copy is installed and the gateway calls your instance instead. For voice and video, point the matching setting at the existing instance. Either way the gateway’s view is identical: a configured URL it can call.

[!WARNING] The browser (CDP) and web_search tools reach out to the network. On hardened or air-gapped deployments review egress and the air-gapped setting before enabling them — the gateway only calls a sidecar that you have wired.

Where to next