Package Manager (PM) & Installation
Relevant source files
The following files were used as context for generating this wiki page:
The Package Manager (PM) module manages the isolated runtime environments required by Hermes Agent. It handles the installation, synchronization, and execution of dependencies across different platforms including Linux, macOS, and Windows. PM ensures that the agent operates within a predictable environment by managing Python interpreters, virtual environments, and cross-platform tools.
The installation process leverages a shell-based bootstrap mechanism for Unix-like systems and a Python-driven environment builder for all platforms. This architecture separates the core agent logic from the host system's global dependencies, preventing version conflicts and ensuring reproducibility.
System Architecture
The PM architecture relies on three primary components: the Command Line Interface (CLI), the Environment Manager, and the Installation Scripts. The pm module serves as a bridge between the raw source code and a functional runtime.
Component Overview
| Component | File Reference | Primary Responsibility |
|---|---|---|
| PM CLI | pm/cli.py | Exposes commands for managing skills and environments. |
| Environment Manager | pm/environments.py | Defines logic for creating and activating virtual environments. |
| Bootstrap Script | install.sh | Orchestrates initial setup and dependency resolution on Unix systems. |
| Env Builder | pm/build_env.py | (Referenced in docs) Creates standalone test and development environments. |
Sources: pm/cli.py, pm/environments.py, install.sh, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md:43-60
Installation Flow
The following diagram illustrates the sequence of actions when a user runs the installation script.
The installation script first identifies the host environment to select appropriate binaries. It then prepares a dedicated HERMES_HOME directory to house local data and configuration.
Sources: install.sh:1-50, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md:38-42
Environment Management
Hermes Agent uses isolated environments to maintain stability. The PM module manages these through the EnvironmentManager class, which handles the lifecycle of Python virtual environments.
Environment Lifecycle
The system supports multiple environment groups, typically categorized into dev, test, and runtime. PM uses lockfiles to ensure that the exact versions of dependencies are installed every time.
Key PM CLI Commands
The pm package provides a CLI for managing aspects of the agent's runtime.
| Command | Action | Description |
|---|---|---|
setup | hermes setup | Initializes the environment and prompts for configuration. |
skills install | hermes skills install <slug> | Downloads and registers an optional skill from the registry. |
profile create | hermes profile create <name> | Creates a new user profile with isolated config and data. |
Sources: pm/cli.py:5-30, skills/software-development/hermes-agent-skill-authoring/SKILL.md:30-45
Cross-Platform Compatibility
PM addresses platform-specific requirements through explicit gating and specialized primitives. This is crucial for components that interact with the host operating system, such as process management and file system access.
Platform Gating Logic
Code within the PM and skill modules must explicitly check the platforms metadata. The system distinguishes between portable logic and OS-bound primitives.
The Package Manager ensures that utf-8 encoding is used for all file operations, especially on Windows where the system locale might differ.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md:95-120, skills/software-development/hermes-agent-skill-authoring/SKILL.md:90-105
Developer Workflow
For developers, PM provides an activate script (or activate.ps1 for PowerShell) that sets up the shell environment to use the localized hermes executable.
Environment Activation Procedure
- Open a terminal in the repository root.
- Execute
source ./activate(Unix) or. .\activate.ps1(PowerShell). - The script defines a
hermesfunction that points to the current worktree's interpreter. - Run
hermes --versionto verify the environment.
The activation script prevents global command conflicts by shadowing any system-wide hermes installations while the session is active.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md:43-55, pm/environments.py:45-60
Summary
The Package Manager and Installation system provide a robust foundation for Hermes Agent by isolating dependencies and managing platform complexities. By using a combination of shell bootstrapping and Python-based environment management, PM ensures that both users and developers have a consistent, reproducible experience across Linux, macOS, and Windows. All modifications to the agent's environment are funneled through PM to maintain system integrity and security.