Deployment Overview of Hermes on Server¶
Prerequisites and Basic Requirements¶
Before proceeding with the installation, ensure the host system meets the following requirements:
-
Operating System: Ubuntu (optimized for this distribution).
-
Privileges: Root or
sudoaccess is required to install system packages and manage services. -
Required Packages:
-
git -
curl -
System Dependencies:
-
For Linux systems using
glibc, thelibatomic1package must be installed. -
For
musl-based distributions,libstdc++is required.
FQDN of the final panel on the hostkey.in domain¶
| Parameter | Value |
|---|---|
| Prefix | hermes |
| Domain | hostkey.in |
| Full template | hermes{Server_ID_from_Invapi}.hostkey.in |
File and Directory Structure¶
The application utilizes a dedicated home directory for its runtime environment, data, and logs.
-
Application Home:
~/.hermes(Default) -
Installation Directory: The location where the agent source is cloned (typically within the Hermes home directory).
-
Configuration Files:
-
.env: Environment variables located in~/.hermes/. -
config.yaml: Main application configuration located in~/.hermes/. -
Logs:
~/.hermes/logs/install.logand other runtime logs within the home directory. -
Data Directories:
-
~/.hermes/cron -
~/.hermes/sessions -
~/.hermes/pairing -
~/.hermes/hooks -
~/.hermes/image_cache -
~/.hermes/audio_cache -
~/.hermes/memories -
~/.hermes/skills
Application installation process¶
The application is installed using a specialized installation script (install.sh) that performs a multi-stage bootstrap process. The installation follows these steps:
-
System Preparation: Installation of required system packages like
git. -
Repository Acquisition: The Hermes Agent source code is cloned from the official repository into the installation directory using a "blobless" clone to optimize bandwidth and storage.
-
Toolchain Provisioning: A private, pinned version of the
uvpackage manager is downloaded and staged to ensure environment isolation. -
Python Environment Setup: The installer downloads and installs a specific, managed Python interpreter (as defined in the project's lock files) using
uv. -
Dependency Management: All Python dependencies are installed into a dedicated virtual environment via the package manager.
-
Product Building: The application builds its command-line interface (CLI), TUI/Web components, and optionally the desktop application.
-
Configuration Initialization: Example configuration files (
.env.exampleandcli-config.yaml.example) are copied to their active locations in the user's home directory with restricted permissions (600).
Access Rights and Security¶
-
User Permissions: The installation is designed to run under a specific user profile, but requires
sudofor system-level dependency management during the bootstrap phase. -
File Security: Sensitive configuration files like
.envare set withchmod 600to ensure they are only readable by the owner. -
Shell Integration: The installer automatically updates the user's shell configuration file (e.g.,
.bashrc,.zshrc, or.profile) to add the Hermes command path to the systemPATH.
Custom Scripts and Additional Setup¶
The installation process includes several automated setup actions:
-
Environment Configuration: Automated creation of subdirectories for sessions, hooks, caches, and skills.
-
Shell Path Integration: A script logic is appended to the user's shell configuration files to ensure the
hermescommand is available in new terminal sessions without manual path modification. -
Gateway Installation: If configured, a gateway service is installed via the application's internal management commands.
Application Update Instructions¶
To update the Hermes Agent, use the built-in update mechanism:
This command synchronizes the local repository with the configured update channel (either stable or main) and ensures all dependencies are aligned with the new version.