AiHummer
English▾
Sign inAccount
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Getting started/Installation

Installation

v1.2.x · updated 2026-08-04

AiHummer installs host-native. Installation starts in your personal account at my.aihummer.ru: you register, obtain a personal install link and run a single command on your server. The install script downloads a signed bundle for your architecture, lays out a single install root under ~/.aihummer (in the home directory of the user who ran the installer), registers systemd units, and optionally provisions sidecars. There are no containers anywhere in this process.

[!NOTE] This is a host-native install — a release tarball running under systemd, not Docker. The gateway, sidecars and plugins each run as their own systemd service.

[!NOTE] What you’ll need before you start:

  • a Linux server (x86_64 or arm64) you can reach over SSH;
  • sudo rights (or a willingness to install rootless — see below);
  • PostgreSQL with the pgcrypto extension — or let the installer provision a user-mode cluster (in rootless mode it does this itself);
  • an account at my.aihummer.ru to get your personal install link.

The full requirements list is on the Requirements page.

There is no public install script — the install link is personal and issued in your account portal:

  1. Register at my.aihummer.ru (phone number + password; an e-mail address is needed as well).
  2. Open the “Installation” screen and click “Get personal install link”.
  3. The portal shows a ready-to-run command with your personal link.

More about the portal itself (billing details, documents, plans) is on the Personal account page.

Step 2: one-command install

Copy the command from the “Installation” screen and run it on your server (Linux x86_64/arm64):

curl -fsSL -o install.sh "<your personal install link>" && sudo bash install.sh

The personal link looks like https://my.aihummer.ru/dl/<token>/install.sh and is bound to your account.

[!IMPORTANT] The link is single-use: it works for exactly one installation. The moment the installer has fetched install.sh through it, the link counts as spent. Running the same command again returns a “link already used” error — that is a safeguard, not a failure. What to do: open the “Installation” screen in your portal and mint a new link; it is free and instant.

The 30 days apply to artifact downloads, not to re-running the installer: an already-installed instance keeps updating through its link long after the link has been spent on the install.

The script detects your CPU architecture, downloads the matching bundle along with its .sha256 checksum and cosign .sig signature, verifies both, unpacks the install root and registers the gateway service. See the Changelog for the current release.

The personal link also binds the instance to your customer portal account: the installer stores the token from the link, the instance sends it on its first registration with the vendor, and the portal links the instance to your account automatically. Your e-mail immediately becomes the instance’s verified contact — no separate “attach and verify an e-mail” step in the Web UI, and the license is delivered with no manual steps.

[!WARNING] Your personal link is your key to the distribution. Do not publish it: anyone holding the link can download builds on your behalf until the token expires.

Install root layout

Everything lives under one directory. Which one depends on how you ran the installer:

How you installed Install root Configuration Service runs as
Normal install (with sudo) /home/.aihummer /etc/aihummer/gateway.env A dedicated aihummer service account
Without root (rootless) ~/.aihummer ~/.aihummer/etc/gateway.env Your own user

A normal install does not put files in your home directory and does not run the service as you: it creates a dedicated unprivileged aihummer user. That is deliberate — compromising the service does not hand an attacker your personal files.

The layout inside the root is the same in both modes (a normal install shown):

/home/.aihummer/
├── bin/        gateway binary and the aihummer CLI
├── etc/        configuration (gateway.env)
├── share/      static assets for the administration interface
├── sidecars/   optional STT/TTS/etc services
├── plugins/    installed marketplace plugins
├── systemd/    unit files (symlinked into /etc/systemd/system)
├── state/      runtime state
├── data/       blob/media storage
└── logs/       service logs

The systemd unit files generated into systemd/ are symlinked into /etc/systemd/system/, so they are managed with regular systemctl commands.

Rootless install

sudo/root privileges are not required. If you run the install command without sudo, the installer switches to rootless mode: units are registered in the systemd --user scope (files in ~/.config/systemd/user), the aihummer CLI and cosign land in ~/.aihummer/bin, and if AIHUMMER_DATABASE_URL is not set the installer provisions a user-mode PostgreSQL cluster inside the install root. Services are managed with systemctl --user .... To have the services start at host boot (not only at user login), enable lingering:

loginctl enable-linger $USER

Sidecar selection

The lightweight media sidecars — STT (faster-whisper), TTS (edge-tts) and video — install out of the box, with no questions or flags: round-trip voice works immediately. Any of them can be disabled with the environment variables AIHUMMER_SKIP_STT=1, AIHUMMER_SKIP_TTS=1, AIHUMMER_SKIP_VIDEO=1.

Web search (SearXNG) and the browser (CloakBrowser) are baked into the signed bundle and install offline by default — the installer no longer asks about them. Flags override that — this is the full list:

Flag Effect
--no-search / --no-browser Skip this sidecar
--external-search=URL / --external-browser=URL Use an existing service at this URL instead of installing
--browser-engine=cloak|chrome Browser engine (default cloak)
--with-search / --with-browser Redundant since v1.0.14 — this is already the default
--with-embedder Install the semantic embedder (opt-in: pulls PyTorch — hundreds of MB)

Search and browser install without a tty too: their payloads come from the bundle, so no internet access is needed for them. Both installs fail open — a missing payload or an unsupported Python version leaves the service unconfigured and never aborts the install. The embedder can also be enabled with AIHUMMER_WITH_EMBEDDER=1; without it memory runs on lexical fallback search. The UI language is set by AIHUMMER_LANG=ru|en (otherwise the installer asks on a tty). The PostgreSQL connection is prompted on a tty; for non-interactive installs set AIHUMMER_DATABASE_URL in advance. On a tty the installer also offers restore from a backup.

# Install the gateway with the embedder, without the browser (search is on by default)
curl -fsSL -o install.sh "<your personal install link>" && sudo bash install.sh \
  --with-embedder --no-browser

Because sidecars are addressed by URL, you can freely mix native and external ones and point several gateways at one shared sidecar.

How the build’s authenticity is checked

The personal link from your account portal always installs the current release — that is the standard and only path. There is no “newer version” to pick: you get the build the vendor shipped for production use.

Every artifact — for the first install and for every update alike — arrives as a tarball for your architecture, accompanied by a .sha256 checksum and a .sig (cosign) signature. The installer verifies both before it unpacks anything. You never have to verify them by hand.

Expected result: the checks pass silently and the install continues. If either one fails, the installer stops with an error and leaves the running version untouched — a corrupted or substituted file never reaches your server.

If the vendor has invited you to an early-testing programme, the “Installation” screen in your portal shows a switcher and issues a separate link for the option you pick — see Instance.

Verify the installation

After the installer finishes, check the service and the readiness endpoint:

systemctl status aihummer-gateway
curl -fsS http://localhost:8780/healthz
curl -fsS http://localhost:8780/readyz

/healthz reports liveness and version; /readyz checks PostgreSQL and returns 503 while the database is unreachable. The bundled aihummer CLI also provides aihummer status and aihummer doctor for a quick health overview.

What you’ll see after a successful install: the aihummer-gateway service in active (running), a 200 from /healthz and /readyz, and the initial admin password in /home/.aihummer/etc/initial-admin-password.txt (on a rootless install, ~/.aihummer/etc/initial-admin-password.txt) for first login.

Production checklist

A single install command gets the gateway running, but it is not yet production-ready. Before exposing it, complete:

  • TLS — terminate HTTPS in front of the gateway (reverse proxy / your own certificate); never expose the plain port on an untrusted network.

  • 🔴 Enable WebSocket support on the reverse proxy. The mobile and desktop app connects to the gateway over wss://, so the proxy must pass the Upgrade and Connection headers through. A proxy without it answers with an ordinary page and status 200 instead of 101 Switching Protocols — the app reads that as “the service is not responding”, while the gateway is healthy and its log shows no error at all. In Nginx Proxy Manager this is the Websockets Support toggle on the Proxy Host; in plain nginx it is proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; plus proxy_http_version 1.1 in the location block.

    One command to check it (expect 101, not 200):

    curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  https://your-domain/

  • Change the admin password and delete initial-admin-password.txt; set an auth issuer (AIHUMMER_OIDC_ISSUER / LDAP / SAML) before exposing /admin/*.

  • Back up the master key and database — record AIHUMMER_MASTER_KEY (secrets are unrecoverable without it) and set up regular PostgreSQL backups.

  • Wire a real model — set AIHUMMER_LLM_* (or BYOK); without it replies come from the deterministic mock.

  • Connect at least one channel (Telegram to start) and bind an agent to it.

See First login, Configuration and Backups & DR for the details.

If it didn’t work

  • “link already used” / the install won’t run a second time — the link is single-use and a previous attempt already spent it. Mint a new one on the “Installation” screen in the portal and run the command again.
  • curl: (22) … 404 or “link invalid” — the link was copied incompletely or has expired. Same cure: a fresh link.
  • “unsupported architecture” — the install supports Linux x86_64 and arm64; there is no bundle for other platforms.
  • /readyz returns 503 — the gateway can’t see PostgreSQL. Check AIHUMMER_DATABASE_URL, database reachability, and that the pgcrypto extension is created (CREATE EXTENSION IF NOT EXISTS pgcrypto;).
  • The service didn’t start — inspect systemctl status aihummer-gateway and journalctl -u aihummer-gateway; for a quick diagnosis run aihummer doctor.
  • Installed without sudo, services stop after logout — enable lingering: loginctl enable-linger $USER (see rootless).
  • Signature verification failed — do not proceed with the install; retry later or get a fresh link. The artifact is always verified against its .sha256 and cosign .sig.

Where to next

  • First run: see First login to retrieve the initial admin password from /home/.aihummer/etc/initial-admin-password.txt (on a rootless install, ~/.aihummer/etc/initial-admin-password.txt).
  • Tune the deployment: read Configuration.
  • Want a guided first run? Use the Quickstart.