Skip to main content
✦HERMINA · YOUR PERSONAL HARNESSExplore
HERMINA
ENPT
Get Started
Docs/Access and permissions

Access and permissions

Hermina has two access boundaries: management access to the server and conversation access to each agent. Configure both before exposing an instance or inviting users.

Management API keys

Protected API routes expect:

Authorization: Bearer <api-key>

Manage keys locally:

hermina angels key
hermina angels key generate
hermina angels key delete <prefix>

API keys are instance-wide and unscoped. A valid key can administer every agent and reach privileged features such as environment settings, workspace files, and shell access.

Use a separate key per device or operator when practical. That makes rotation possible without disconnecting everyone.

The Web/Desktop login screen supports three access paths:

  • A passphrase entered directly.
  • A one-time code created by an authenticated hermina connect --code command.
  • A QR approval confirmed in an Android app that already has access to the server.

For a public HTTPS domain, enable mandatory two-factor login from an SSH shell:

hermina mfa
hermina mfa --status

Until enrollment is complete, public access stays locked instead of falling back to passphrase-only authentication.

The public web flow then requires the passphrase followed by a six-digit TOTP code. The server returns a random 12-hour session token, kept in browser session storage and revoked whenever the API restarts. Raw long-lived API keys remain compatible with direct loopback, LAN, and Tailscale clients, but are rejected on the reverse-proxied public path.

If the authenticator is lost, use hermina mfa --reset over SSH. This replaces the TOTP secret and revokes current sessions.

The QR approval request does not contain an API key. Its result can only be read by the browser that created it, using a separate random polling token.

Safe network exposure

Follow these rules:

  • Do not expose port 3456 directly to the internet.
  • Prefer Tailscale or another private VPN.
  • If public reachability is required, use an HTTPS reverse proxy and firewall.
  • Preserve Authorization and WebSocket upgrade headers at the proxy.
  • Ensure the proxy manages X-Forwarded-For; Hermina uses it to enforce MFA on the public path.
  • Restrict access to .env, api-keys.txt, session directories, and backups.
  • Never log connection QR contents, API keys, provider tokens, or authorization headers.

The Web client stores MFA sessions in sessionStorage. Private connections may still persist long-lived keys; Android uses app preferences and the extension uses browser extension storage. Treat a compromised device profile as a compromised Hermina credential.

Sender allowlist

Restrict who can message an agent:

hermina allowlist support --numbers=5511888888888,5511777777777

Show the current policy:

hermina allowlist support

An open allowlist allows every sender who can reach the channel. Use it only for intentionally public agents whose tools and data are safe for public use.

Slash-command administrators

Administrators can run all supported slash commands. Regular users can run only the configured list.

hermina commands support \
  --allow-admin=5511888888888 \
  --user-commands=help,whoami,status

Use the exact platform ID returned by /whoami. WhatsApp may identify an account as a phone-number JID or as a value ending in @lid.

To intentionally configure no administrators:

hermina commands support --allow-admin=''

Hermina stores an internal sentinel so command gating remains enabled rather than treating an empty list as unrestricted.

Group policy

For WhatsApp:

hermina groups support on
hermina groups support off

Enabled WhatsApp groups require a mention by default. Keep that behavior in active group chats to prevent the agent from responding to unrelated conversation.

For Telegram:

hermina telegram-groups support on

Here, on means mention-only mode. Confirm the current status before assuming the same wording maps to the same underlying setting on every platform.

Tool and shell risk

Permissions inside the messaging layer do not make every tool safe. Review which tools are enabled for each platform and persona.

In particular:

  • Shell can execute commands in a container or, for host-based agents, on the server.
  • File tools can read profile or workspace data available to the runtime.
  • Browser and web tools can send information to external services.
  • Messaging tools can act in connected accounts.
  • Scheduled jobs continue to run without an interactive user present.

Use container agents for untrusted conversations, keep host-based angel agents tightly restricted, and follow least privilege for channel accounts and API credentials.

Key rotation after device loss

  1. List keys locally and identify the lost device's key.
  2. Generate a replacement key if needed.
  3. Delete the compromised key by prefix.
  4. Reconnect the intended client.
  5. Review API and proxy logs without printing secret values.
  6. Rotate provider or channel tokens too if they were exposed through the device or shell.

See Connect your apps for pairing workflows.