systemd & health checks — AiHummer Docs

AiHummer is host-native: it deploys as a release tarball running under systemd, not in containers. This page covers where it lives on disk, how to probe its health, and what to lock down before you put it in front of users.

Install root & systemd units

Everything lives under a single install root, /home/.aihummer, laid out into bin/ etc/ share/ sidecars/ plugins/ systemd/ state/ data/ logs/. The gateway config file is /home/.aihummer/etc/gateway.env.

The systemd unit files are kept under the install root and symlinked into /etc/systemd/system/, so the gateway and each sidecar are ordinary services you can start, stop and inspect with systemctl and journalctl. Each sidecar runs under its own unit — see Sidecars.

Health & readiness probes

The gateway exposes two distinct probes:

Probe	Endpoint	Meaning
Liveness	`GET /healthz`	Process is alive; returns the version
Readiness	`GET /readyz`	Checks PostgreSQL; returns 503 if the DB is down

Use /healthz for “is the process up” and /readyz for “can it actually serve a turn”. Behind a reverse proxy or load balancer, point the readiness check at /readyz so a gateway with no database is taken out of rotation.

curl -fsS http://127.0.0.1:8765/healthz   # 200 + version
curl -fsS http://127.0.0.1:8765/readyz    # 200 ready, 503 if Postgres is unreachable

[!NOTE] PostgreSQL is the only hard dependency. Without a reachable database the gateway runs in a degraded health-only mode and /readyz reports 503.

Smoke test

After an install or upgrade, run the bundled smoke test to confirm the deployment answers correctly end to end:

deploy/host/smoke.sh

Managing services with the CLI

The aihummer CLI is the front door for day-to-day operations — it manages the gateway and sidecars rather than driving systemctl by hand:

aihummer up         # install / bring services up
aihummer restart    # restart the gateway
aihummer stop       # stop services
aihummer status     # show service status
aihummer logs       # tail logs (optionally: aihummer logs <svc>)
aihummer doctor     # run diagnostics

See the CLI reference for the full command set, including backup, restore, update and uninstall.

Production pre-flight checklist

Before exposing AiHummer to real traffic, work through this list:

Set the master key. Provide AIHUMMER_MASTER_KEY (base64, 32 bytes) so the secrets vault and BYOK are encrypted at rest.
Configure enterprise auth. Wire OIDC, LDAP and/or SAML so /v1/admin/* is protected. Without an auth issuer the admin surface trusts development headers.
Set the inbound secret. Provide AIHUMMER_INBOUND_SECRET so connectors authenticate to /v1/inbound/*.
Lock down risky tools. Restrict or disable code_exec, tighten egress, and scope db_query to a read-only DSN.
Terminate TLS at a reverse proxy. Run the gateway behind a proxy that handles HTTPS; the gateway itself serves plain HTTP.

[!WARNING] Without an OIDC/LDAP/SAML issuer configured, the admin API falls back to trusting development headers. Never expose such an instance to an untrusted network — configure enterprise auth first.

Where to next

The transport model for speech and tool services: Sidecars.
Backups, the master key and disaster recovery: Backups & disaster recovery.
Metrics, traces and what to watch: Observability.