AiHummer
English▾
Log in
v1.0.x▾
v1.0.xstable
{ }Swagger
Architecture/Sidecars

Sidecars

v1.0.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. A capability is only active when its URL is configured; until then the gateway runs without it. This keeps a minimal install to 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 SEARXNG_URL
9222 Chrome / CDP Chrome (CDP) the browser tool CLOAKBROWSER_CDP_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 environment variable. For the host-native install the voice sidecars (STT/TTS) are configured for you; the rest you enable as needed.

# gateway.env — voice in/out (auto-set by the installer for STT/TTS)
AIHUMMER_STT_URL=http://127.0.0.1:8001
AIHUMMER_TTS_URL=http://127.0.0.1:8002

# Optional video sidecar
AIHUMMER_VIDEO_URL=http://127.0.0.1:8005

# Tool sidecars
SEARXNG_URL=http://127.0.0.1:8888
CLOAKBROWSER_CDP_URL=http://127.0.0.1:9222

[!TIP] Because each sidecar is just a URL, you can centralise heavy services. Point several gateways at one shared STT/TTS or SearXNG instance instead of running a copy per host.

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, simply set the URL to that existing instance and skip the local install entirely. 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