Deployment Overview of Hermes on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the following system requirements must be met:

• Operating System: Linux (Ubuntu/Debian preferred), macOS, or Android (Termux).

• Privileges:

• Standard user permissions for non-root installations.

• sudo access required for installing system packages and configuring Electron sandboxes on Linux.

• Hardware/Software Dependencies:

• Python 3.11 to 3.13 (Required).

• Node.js (Managed version provided during installation).

• Git (Required for repository cloning).

• C++ Compiler (e.g., gcc, clang) required for building native modules like node-pty.

• Network: Active internet connectivity is required to download the agent, Python runtimes, Node.js binaries, and browser engines.

File and Directory Structure¶

The application follows a split layout between executable code and persistent data:

Data Directory Subdirectories (~/.hermes/)¶

• cron/: Scheduled tasks.

• sessions/: User session data.

• logs/: Application and gateway logs.

• pairing/: Device pairing information.

• hooks/: Custom automation hooks.

• image_cache/: Cached images for vision tasks.

• audio_cache/: Cached audio files.

• memories/: Long-term memory storage.

• skills/: Bundled agent skills and capabilities.

Application Installation Process¶

The installation is performed via a comprehensive shell script (install.sh) that automates the environment setup:

1. System Preparation: The installer checks for and installs build dependencies (e.g., build-essential, python3-dev, libffi-dev).

2. Runtime Management:

3. Installs a managed version of uv to handle Python environments.

4. Provisions a specific Python version (defaulting to 3.11) within a virtual environment.

5. Downloads and installs a compatible Node.js LTS runtime into the Hermes data directory to ensure compatibility with native modules.

6. Repository Deployment: The application source code is cloned from the official repository into the installation directory.

7. Dependency Installation:

8. Python: A virtual environment is created, and all required Python packages are installed via uv.

9. Node.js: All necessary Node modules (including browser automation tools) are installed via npm.

10. Binary Linking: The installer creates user-facing shims (hermes, hermes-agent, and hermes-acp) in the system's PATH to allow command execution from any shell session.

Access Rights and Security¶

• File Permissions: Sensitive files, specifically .env (containing API keys), are restricted with 0600 permissions (read/write only by the owner).

• Sandbox Security: On Linux systems, the installer attempts to configure the Electron sandbox (chrome-sandbox) with root:root ownership and 4755 permissions to ensure secure browser execution.

• Environment Isolation: The launcher scripts explicitly unset PYTHONPATH and PYTHONHOME to prevent environment leakage from the host system into the application runtime.

Custom Scripts and Additional Setup¶

The installation process includes several specialized setup actions:

• Configuration Seeding: Templates for .env (environment variables) and config.yaml are copied to the data directory if they do not already exist.

• Persona Initialization: A default SOUL.md file is created in the data directory to define the agent's personality.

• Skill Synchronization: The installer runs a skill synchronization script to populate the ~/.hermes/skills/ directory with bundled capabilities.

• Browser Configuration: The installer detects system browsers and configures the AGENT_BROWSER_EXECUTABLE_PATH in the .env file to ensure seamless automation.

Application Update Instructions¶

To update the Hermes application to the latest version, use the built-in update command:

hermes update

This command performs a controlled update of the repository code and synchronizes dependencies while attempting to preserve any local configuration changes via Git stashing.