Skip to main content
✦HERMINA · YOUR PERSONAL HARNESSExplore
HERMINA
ENPT
Get Started
Docs/Quickstart

Quickstart

This tutorial gets one agent responding in the Hermina dashboard and, optionally, on WhatsApp. It assumes the server is already installed.

1. Confirm the server is healthy

hermina angels status
hermina status

If the API is not running, inspect it before creating agents:

hermina angels logs --lines 100

2. Connect a management app

If the dashboard will be available on a public domain, configure TOTP first:

hermina mfa

The public login will require the passphrase plus the authenticator code.

Generate a single-use pairing code:

hermina connect --code

Open the Web, Desktop, or Android login screen, enter the server URL shown by the CLI, then enter the six-character code.

For a QR that contains the server URL and a full API key:

hermina connect --qr

A connection QR contains administrative credentials for the whole instance. Display it privately and rotate the key if the QR is shared or captured.

See Connect your apps for manual login and remote-access details.

3. Create your first agent

Choose a short lowercase name and the agent's phone number in international format, without +, spaces, or punctuation:

hermina add support 5511999999999 --lang=en --start=true

The default runtime is a Docker container and the default provider preset is opencode-go. To create an agent with a persona immediately:

hermina add support 5511999999999 \
  --persona=retail/ecommerce-support \
  --lang=en \
  --start=true

List agents and confirm the new runtime is present:

hermina list

4. Configure a provider and model

View the active model:

hermina model support

Configure a provider with an API key:

hermina model support \
  --provider=openai \
  --model=gpt-4o-mini \
  --api-key=YOUR_API_KEY

The key is stored in the agent's .env; non-secret model settings go to config.yaml. If the agent is running, the command applies the change by restarting it.

You can also configure the model from the agent detail screen. See Providers and models for presets, local endpoints, and reasoning levels.

5. Send a dashboard message

In the Web/Desktop app:

  1. Open Agents.
  2. Select support.
  3. Open Chat.
  4. Send a simple, verifiable prompt such as: Reply with your name and one sentence about your role.

Success means the reply streams normally, the selected model is shown, and the session remains available after navigating away and returning.

Test dashboard chat before connecting a messaging channel. This separates model problems from channel problems.

6. Pair WhatsApp

If the agent uses the standard WhatsApp transport:

hermina qr support
hermina logs support --follow

On the agent's WhatsApp account, open Linked devices, choose Link a device, and scan the QR displayed in the logs.

Then check:

hermina bridge support
hermina list

The bridge should report connected and the agent should appear paired. WhatsApp Cloud does not use QR pairing; it requires Meta credentials and a webhook instead.

7. Lock down access

Before inviting users, set an allowlist and command administrators:

hermina allowlist support --numbers=5511888888888,5511777777777
hermina commands support --allow-admin=5511888888888
hermina commands support --user-commands=help,whoami,status

In WhatsApp, send /whoami and prefer the exact returned user ID for admin configuration. Some WhatsApp sessions identify users with an @lid value instead of a phone number.

What to do next