Skip to content

Quick start

This page walks an operator (or an agent acting on the operator's behalf) through bringing up Hivemind from a fresh server.

You will have received an invite URL by email

Hivemind is gated behind single-use invite URLs. If you don't have one yet, email sales@seglamater.com to request design-partner access.

Invite URLs look like https://s.seglamater.app/i/<id>. They expire in 24 hours and burn after a single successful install. If you need a fresh one, just ask.

Server requirements

Resource Recommended Minimum
OS Ubuntu 22.04+, Debian 12+, Rocky 9 Any Linux with kernel ≥ 5.10
CPU 2 cores 1 core
RAM 4 GB 2 GB
Disk 20 GB 10 GB
Docker Engine ≥ 24, with the docker compose plugin same

The install user must be in the docker group, or be root.

Outbound network must reach (HTTPS / 443):

  • registry.seglamater.app — image pull
  • updates.seglamater.app — manifest + install script
  • s.seglamater.app — invite-scoped bundle download

Plus whatever public ingress you intend for Hivemind itself (typically behind a reverse proxy on 80/443).

Install (the one-liner)

On the target server, paste the invite URL into a curl | bash pipe:

curl -fsSL https://s.seglamater.app/i/<your-invite-id> | bash

That command:

  1. Fetches your signed deployment bundle from s.seglamater.app.
  2. Fetches the installer (install.sh) from updates.seglamater.app.
  3. Runs the installer non-interactively against the bundle.

The installer will:

  • Verify the bundle's SHA-256 against our manifest.
  • Pull the hivemind-server image pinned by digest from registry.seglamater.app.
  • Stand up a Docker Compose stack (Postgres + server).
  • Print the next-step URLs and the /srv/hivemind/.env location.

Total time is typically 2–4 minutes on a 4 GB VPS. The installer is idempotent — safe to re-run if anything wedges.

After it finishes

The installer prints (capture all of these):

  • Web UI URL (defaults to http://localhost:8585). Put it behind your own reverse proxy with TLS.
  • Admin bootstrap URL — single-use, used to create the first admin account.
  • /srv/hivemind/.env — contains the database password, signing keys, and other runtime config. Back this up.

If you're handing the install off to an AI agent, the recommended procedure is in the email you received under "For an AI agent operator."

Your first bot — 5-minute walkthrough

After install + admin bootstrap (see Operator notes for how to create the first admin), the fastest way to validate the install is to mint a real bot from a template, add some knowledge, and chat with it.

Step 1 — Pick a template

Open the web UI and navigate to Bots in the top nav (or /bots directly). Click + New bot. The modal opens with a Start from template dropdown at the top. The bundled catalog has five tuned starting points:

Template Tier Use case
Customer support 1 Public-facing tech support
Sales SDR 1 Inbound lead qualification + handoff
Internal IT FAQ 2 Employee IT helpdesk
HR FAQ 2 Routine HR policy questions
Product docs 1 Documentation lookup + linking

Pick one. The bot's name, slug, description, system prompt, and security tier auto-fill from the template's defaults. The Seed N starter knowledge memories toggle controls whether the template's starter knowledge snippets get copied into your bot's knowledge corpus on creation — leave it checked.

Edit the name (e.g. Acme Support) and the slug will auto-derive. You can edit the prompt inline if you want to tailor it to your business immediately, or leave it as the template default and edit later from the bot's detail page.

Click Create from template. You land on /bots/{your-slug}.

Step 2 — Add your knowledge

Click the Knowledge tab on the bot's detail page. You'll see the starter snippets from the template (typically 2–3). Click + Add knowledge to add your own — e.g. your support hours, your pricing tiers, your refund policy, common troubleshooting steps.

Each snippet has a title (admin-side label) and content (what the bot retrieves and uses to ground replies). Keep snippets focused — one concept per snippet, ≤ 4000 characters. The bot's full-text search retrieves the top relevance-ranked snippets at chat time and injects them into the system prompt; smaller, atomic snippets give better retrieval than long documents.

Do not put secrets in knowledge — API keys, customer PII, internal credentials. Knowledge text is sent to the LLM verbatim and stored in your database; treat it like content you'd publish.

Step 3 — Connect chatalot (optional)

If you have a Chatalot instance and want your bot to participate as a real user, click the Integrations tab on the bot detail page → Connect. You'll need a bot:provision-scoped token (cb_…) for your Chatalot instance — generated in Chatalot's admin UI, used once, not persisted (it is not an admin JWT). The integration provisions a bot user + token, encrypts the token at rest in your Hivemind database, and starts the bot listening for inbound messages.

Pick a default community so users can find the bot

Chatalot only shows users in search if they share a community, so a freshly-connected bot in no community is invisible to everyone but the instance owner — "it connected but I can't DM it." In the Connect modal, enter your instance URL + the bot:provision token, click Load communities, and pick a default community. Hivemind adds the bot to it on connect (auto-joining its public channels), so your team can find and message it right away. You can skip this and add the bot to a community later from your Chatalot admin panel.

Where the bot replies — DMs, channels, or both

Each bot has a channel reply mode:

  • DMs only (default) — replies in 1:1 direct messages.
  • Channel @-mention — replies in a channel only when someone @-mentions it by username.
  • Both — DMs and channel @-mentions.

A bot never auto-responds to general channel chatter — in a channel it answers only when directly @-mentioned. To test a DM, open a direct conversation with the bot and send a message; to test a channel, add the bot to a channel and @<bot-username> your question.

See Chatalot integration for the full flow.

Step 4 — Test it

For a public tier-1 bot (e.g. customer-support, sales-sdr, product-docs), you can chat with it directly via the public endpoint — no auth required:

curl -sS https://your-hivemind.example.com/api/v1/public/agents/chat/your-slug \
    -H 'Content-Type: application/json' \
    -d '{"message":"What are your support hours?"}'

The reply JSON contains the bot's response, a conversation_id (reuse this in subsequent calls for multi-turn context), and per-message token + cost figures.

For internal-tier bots (2 or 3), use the authenticated chat path — see the API reference for full details.

Hivemind ships a cosign signature alongside every release manifest. To verify:

# Fetch our public key (pinned by SHA-256 in the email you received).
curl -fsSL https://updates.seglamater.app/.well-known/keys/hivemind.pub \
     -o /tmp/hivemind.pub

# Verify the manifest signature.
cosign verify-blob \
  --bundle <path-to-manifest.json.sig> \
  --key /tmp/hivemind.pub \
  <path-to-manifest.json>

If verification fails, stop and email support@seglamater.com with the error output before doing anything further.

Need help?

Email support@seglamater.com with your customer ID. If the install failed, please include:

  • The full output of the install command.
  • The output of docker compose ps from the install directory.
  • Your server's distro + kernel version (uname -a).