Installation

Install the complete Hermina stack on a Debian or Ubuntu server. The standard installer is designed for a root-managed machine with Docker and systemd.

Before you begin

You need:

A Debian or Ubuntu host with apt-get and systemd.
Root or sudo access.
Internet access to GitHub, Docker, Node.js, Python packages, and your chosen model provider.
Enough resources for the control plane and at least one agent. A practical starting point is 2 CPU cores, 4 GB RAM, and 20 GB free disk.
A trusted way to reach the server: local network, Tailscale, or an HTTPS reverse proxy.

Each default container is limited to 1 CPU and 1 GB RAM. Plan additional capacity for each concurrently active agent.

One-command installation

curl -fsSL https://raw.githubusercontent.com/moonixt/hermina/master/install.sh | sudo bash

The installer performs nine stages:

Installs system prerequisites.
Installs or verifies Docker.
Installs Hermes Agent.
Clones Hermina into /opt/hermina by default.
Creates a Python environment and installs the hermina command.
Builds the Web/Desktop application.
Builds the base agent image.
Generates an API key and starts the management service.
Verifies the CLI, API, build output, and Docker image.

The installer downloads and executes third-party installation scripts for Docker and Hermes Agent. Review install.sh first when your environment requires a controlled software supply chain.

Verify the installation

Run these checks in order:

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

A healthy local API returns a JSON response with "status": "ok". The installer also creates at least one management key in:

/opt/hermina/api-keys.txt

Treat that file as a secret.

Run guided onboarding

hermina onboard

The wizard checks the environment, starts or configures the backend, helps with remote access, selects a provider and model, creates an optional first agent, configures channels, and prints client connection instructions.

If you prefer a minimal setup, skip the optional agent and channel steps. You can add them later from the dashboard or CLI.

Custom installation paths

The installer supports environment overrides. The most common is HERMINA_HOME:

curl -fsSL https://raw.githubusercontent.com/moonixt/hermina/master/install.sh \
  | sudo HERMINA_HOME=/srv/hermina bash

The CLI uses HERMINA_HOME to find agents and project files. Keep the same value in service units and administrative shells if you change the default.

Advanced installer switches include HERMINA_SKIP_DOCKER, HERMINA_SKIP_HERMES, HERMINA_SKIP_DESKTOP, HERMINA_SKIP_AGENT_IMAGE, and HERMINA_SKIP_SERVICES. Use them only when the skipped component is already managed by your infrastructure.

Network access

By default, the API listens on port 3456. Do not expose that port directly to the public internet.

Use one of these patterns:

Pattern	Best for	Notes
Loopback only	Single-machine Desktop/Electron use	Lowest exposure
Tailscale or private VPN	Personal and small-team remote use	Recommended for most self-hosted setups
HTTPS reverse proxy + firewall	Publicly reachable server	Preserve `Authorization` and WebSocket upgrade headers

Continue with Quickstart to connect a client and create an agent.

Updating an installation

The installer can update an existing Git checkout only when it can fast-forward the configured branch. Back up persistent data before updating:

agents/
profile/, groups/, workspace/, and settings/
personas/custom/
api-keys.txt
Custom reverse-proxy and service configuration

Docker images and application builds can be recreated from source; agent profiles and databases cannot.