Skip to main content
✦HERMINA · YOUR PERSONAL HARNESSExplore
HERMINA
ENPT
Get Started
Docs/Connect your apps

Connect your apps

Web, Electron, Android, and the browser extension connect to a Hermina server with a base URL and an instance-wide API key. Pairing codes and QR codes make that setup easier.

Before connecting

Confirm the management API is healthy:

hermina angels status
curl -fsS http://127.0.0.1:3456/health

The client must be able to reach the same base URL. 127.0.0.1 works only on the server itself. For another device, use a private IP, Tailscale address, or HTTPS domain.

Before opening a public HTTPS domain, enroll an authenticator over SSH:

hermina mfa

Public web login then asks for the instance passphrase and the current TOTP code. Pairing-code and approval-QR login remain intended for private/direct connections.

Pair with a short code

hermina connect --code

The CLI prints:

  • The server URL.
  • A six-character one-time code.
  • The remaining validity period.

On the client login screen, enter the URL and choose pairing-code login. The server exchanges the code for an API key and the client stores the connection.

Pairing codes are held in server memory and expire. Generate a new code if the API restarts or the displayed code is rejected.

Pair with a QR

On the Web/Desktop login screen, choose Approve in app. The browser displays a QR that contains a short approval request, not an API key. In an Android app that is already connected to the same server, open the scanner, scan the QR, and approve the session. The browser connects automatically.

Only the browser that created the QR can retrieve the approval result.

Connect a new app directly with a QR

hermina connect --qr

Scan the QR from the Android setup screen or a compatible client. The QR contains two lines: the server URL and an API key.

The app-connection QR is not the WhatsApp QR. The first authenticates a management client to Hermina; the second links a WhatsApp account to one agent.

Enter the URL and key manually

List the server's keys locally:

hermina angels key

Then enter the base URL and one key on the client login screen. A client validates the connection by checking server health and loading the agent list.

Do not append /api in the Web/Desktop or Android login screen unless that client explicitly asks for an API base. The standard clients add /api to protected routes themselves.

Manage API keys

Generate a key for a new device or operator:

hermina angels key generate

Delete a lost or retired key by a unique prefix of at least eight characters:

hermina angels key delete <prefix>

Restart is not required after editing the key file through the CLI. Test every remaining client after rotation.

Keys are instance-wide: they are not restricted to a user, agent, or role. Anyone holding a valid key can reach administrative endpoints, including configuration and shell capabilities.

Multiple servers

Web/Desktop and Android can save more than one server connection. Use clear connection names such as Home, Production, and Lab.

Some multi-server views aggregate lists, but not every action is guaranteed to route across all servers in the same way. Avoid duplicate agent names across connected instances and verify the active server before performing destructive operations.

Remote access patterns

Use one of these approaches:

Tailscale or private VPN

This is the recommended default for personal and small-team installations. The Hermina CLI prefers a detected Tailscale IPv4 address when printing connection information.

LAN

Use the server's private address only on a trusted network. Android supports cleartext HTTP for LAN compatibility, but keys remain visible to anyone able to inspect that traffic.

Public HTTPS

Put Nginx or Caddy in front of the API, terminate TLS, restrict the origin with a firewall, preserve the Authorization header, and support WebSocket upgrades for the interactive shell.

Enable hermina mfa, keep port 3456 closed publicly, and ensure the proxy sets X-Forwarded-For. The domain accepts short-lived MFA sessions instead of raw long-lived API keys.

Never expose port 3456 directly to the public internet.

Connection troubleshooting

If login fails:

  1. Open <server-url>/health from the client device.
  2. Confirm the URL has the correct scheme, host, port, and optional path.
  3. Generate a new pairing code.
  4. Verify the key still exists with hermina angels key.
  5. Check hermina angels logs --lines 100.
  6. Inspect reverse-proxy forwarding and CORS only after direct network reachability works.