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

Quickstart

v1.2.x · updated 2026-07-20

This quickstart takes you through your first AiHummer run — from zero to a first agent replying in a channel. It is written for someone doing this for the first time: every step ends with what you should see, and there is an “If it didn’t work” section at the end.

First, pick your path

There are two ways to get AiHummer (full comparison in the Introduction):

  • Cloud — we run the server, you get a ready address. Nothing to install. → go to Path A: cloud.
  • Self-hosted (your own server) — you install AiHummer on your Linux server with one command. → go to Path B: your own server.

Both paths then converge on the shared steps — first agent and first channel.

Path A: cloud

What you’ll need: an e-mail address, a phone number and a bank card (for the trial the bank charges ₽1 and refunds it immediately).

  1. Register at my.aihummer.ru: enter your e-mail, phone and password, accept the two consents. You’ll see the account-confirmation screen.
  2. Confirm the account — by call (enter the last digits of the incoming number) or with the code from the e-mail. You’ll see that sign-in happened automatically and the onboarding wizard opened. Details: Registration & sign-in.
  3. In the wizard pick the “Cloud” path, then a plan (monthly/yearly). The entry plan comes with a 10-day free trial. Details: Plans.
  4. Fill in your billing details (individual or company/sole proprietor) — they are needed for the invoice and act.
  5. Pick a subdomain name (your address will be <name>.cloud.aihummer.ru) and pay. You’ll see the “Preparing your assistant” status with progress. Details: Order & payment.
  6. Wait for provisioning (usually a few minutes). When the status turns “Your assistant is running”, click “Open panel” — the web admin UI of your instance opens. Details: Instance dashboard.

Configuration continues in the web admin UI — go to your first agent. The admin password for a cloud instance is set when you first open the panel (the separate password file used in self-hosted is not needed here).

Path B: your own server

What you’ll need: a Linux server (x86_64 or arm64), sudo rights, and PostgreSQL (or let the installer provision it). Full list: Requirements.

There is no public install script — the link is personal. Register at my.aihummer.ru, open the “Install” screen and click “Get my personal install link”. You’ll see a ready command with a copy button.

Step 2. Install with one command

Run the copied command on the server:

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

The installer detects the architecture, downloads and verifies the signed bundle, lays out the install root at ~/.aihummer and registers the gateway service under systemd. You’ll see the install-step log and, at the end, a service-started message. Full details (release channels, sidecars, rootless install): Installation.

Step 3. Point at PostgreSQL

The only hard dependency is PostgreSQL with the pgcrypto extension. The installer wires the connection up for you; to set the database manually, use the AIHUMMER_DATABASE_URL config option:

AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer?sslmode=disable
-- once, in the target database
CREATE EXTENSION IF NOT EXISTS pgcrypto;

Database migrations apply automatically on startup.

Step 4. First login

Once the service is up, open the admin Web UI on the server (private port :8781 by default):

http://localhost:8781/

On an empty database a login admin is created and the initial password is written to ~/.aihummer/etc/initial-admin-password.txt. Read it, sign in, then change the password and delete the file immediately — step by step in First login.

Step: create your first agent

This step is shared by cloud and self-hosted. In the web admin UI open “Agents” → “+ Create”, set a name, a persona (system prompt) and, optionally, a dedicated model. You’ll see the new agent as a tile in the list. Full detail, with character and behaviour tuning: Agents.

Step: connect your first channel

To let messages reach AiHummer, add a channel:

  • Telegram — the most production-ready connector; an end-to-end walkthrough “from BotFather to the first message” is in Telegram.
  • Sessions in Web UI — the fastest way to test an agent before connecting an external channel.
  • MAX — a Russian messenger, also available.

The connector is installed on the Plugins/Marketplace screen, then configured on the Channels screen, where the “Bindings” block sets which agent runs that channel. Send a message to the channel and watch a turn flow end to end.

Talk to the agent right from the admin UI

A channel is not required for a first test: on the “Sessions” page the “+ New session” button opens a chat with an agent right inside the admin UI. In the composer you can attach files (images and documents — the model receives the extracted text), and two toggles above the thread reveal per-turn cost and tool output — handy for seeing what the agent did at each step.

[!TIP] You can also call AiHummer directly over its OpenAI-compatible API with no channel at all:

POST /v1/chat/completions
Content-Type: application/json

{"model": "default", "messages": [{"role": "user", "content": "Hello"}]}

Set "stream": true for SSE streaming.

Remember the mock model

Until you connect a real model, replies come from a deterministic mock — handy for testing channels, routing and agents with no model cost. How to connect a real provider (OpenAI, Anthropic, YandexGPT, GigaChat, Codex via a ChatGPT subscription and more) is on the Models page.

[!NOTE] A real model is never mandatory: AiHummer runs on free/local OpenAI-compatible endpoints and a Codex/ChatGPT-subscription transport.

If it didn’t work

  • The install command failed — check that you run it on Linux x86_64/arm64 and that the personal link is not stale (it lives 30 days; get a fresh one on the “Install” screen). Diagnostics: Installation.
  • The admin UI won’t open — the Web UI listens on the private port :8781, not the public :8780. Check the service: systemctl status aihummer-gateway.
  • Can’t find the initial password — it is in ~/.aihummer/etc/initial-admin-password.txt, not in the logs. See First login.
  • Cloud payment failed — the subscription status on the dashboard shows the reason; retry, or (for companies) choose pay-by-invoice, see Order & payment.
  • The agent doesn’t reply in a channel — make sure the channel is bound to an agent in the “Bindings” block, and that the sender is known to the system (by default the agent only answers known users), see Channels.

Where to next