Deployment Overview of Hermes on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful installation, the server must meet the following minimum requirements:

Operating System: Linux (Ubuntu/Debian preferred), macOS, or Android (Termux).
Privileges:
Non-root users can install the agent in their home directory.
Root/Sudo privileges are required for installing system-level dependencies (e.g., build-essential, git, ffmpeg).
Hardware/Software Dependencies: | Component | Requirement | Purpose | | :--- | :--- | :--- | | Python | version 3.11 to < 3.14 | Core application runtime | | Node.js | Version 22.22+, 24.11+, or 26+ | Browser automation and TUI tools | | Git | Latest stable version | Repository management | | C++ Compiler | g++ or clang++ | Building native modules (e.g., node-pty) |

File and Directory Structure¶

The application uses a split architecture to separate the executable code from user data and configuration:

Application Code: Located in the installation directory (typically /usr/local/lib/hermes-agent for root installs or ~/.hermes/hermes-agent for users).
Data & Configuration Directory: Located at $HERMES_HOME (defaults to /root/.hermes for root or ~/.hermes for users).
config.yaml: Main application configuration.
.env: Environment variables and API keys (permissions set to 0600).
SOUL.md: Global persona/personality settings.
skills/: Directory containing bundled or custom skills.
logs/: Application and gateway logs.
sessions/: Session data.

Application Installation Process¶

The application is installed via a comprehensive installation script (install.sh) that performs the following actions:

Environment Preparation: Detects the operating system, architecture, and shell type. It unsets inherited PYTHONPATH or PYTHONHOME variables to prevent module shadowing.
Dependency Management:
Installs a managed version of uv for Python package management.
Provisions a compatible Python interpreter (3.11–3.13) via uv.
Downloads and manages a specific Node.js LTS version to ensure compatibility with native modules.
Repository Provisioning: Clones the Hermes Agent repository from GitHub using either SSH or HTTPS (with automatic fallback to blobless partial clones if throttled).
Runtime Environment Setup:
Creates a Python virtual environment (venv) within the installation directory.
Installs application dependencies in "editable" mode using uv sync for hash-verified security where possible.
System Integration:
Configures shell paths (e.g., .bashrc, .zshrc, or .config/fish/config.fish) to ensure the hermes command is available in all terminal sessions.
Installs system-level libraries required for browser automation and media processing (e.g., libatomic1, ffmpeg, ripgrep).

Access Rights and Security¶

File Permissions: The .env file containing sensitive API tokens is restricted with chmod 600.
Command Wrappers: The installed hermes command uses a shell shim that unsets PYTHONPATH and PYTHONHOME before execution to prevent environment leakage.
Sandbox Security: On Linux, the Electron sandbox helper (chrome-sandbox) is automatically configured with root:root ownership and 4755 permissions if required for the desktop application.

Custom Scripts and Additional Setup¶

The installation process includes several specialized setup actions:

Configuration Templating: The script generates default configuration files (config.yaml, .env, SOUL.md) from provided templates.
Skill Synchronization: A dedicated tool (skills_sync.py) is used to seed the application with bundled skills into the $HERMES_HOME/skills/ directory.
Browser Configuration: The installer detects existing system browsers and configures an explicit path in .env if a compatible browser (like Chromium) is found, preventing issues with sandboxed versions like Snap.

Application Update Instructions¶

To update the Hermes Agent to the latest version:

Use the built-in update command:
```
hermes update
```
The update process performs a git pull --ff-only and resets the working tree to match the remote branch, ensuring the installation remains clean and synchronized with the official repository.

Available Ports for Connection¶

The application primarily operates via CLI and local services. If the Gateway service is enabled, it manages background processes for messaging platforms (Telegram, Discord, Slack, WhatsApp). Specific network ports are managed by these individual platform integrations rather than a single static port.