This page documents the infrastructure supporting the Hermes Agent lifecycle, including automated testing sharding, supply-chain security audits, multi-platform distribution (Docker, PyPI, Nix), and the CalVer-based release process.
Hermes Agent utilizes GitHub Actions to orchestrate a high-frequency release cycle. The pipeline ensures that the "self-improving" nature of the agent does not compromise system stability or security. The ci.yml acts as a centralized orchestrator managing change detection to trigger only necessary sub-workflows, optimizing run time and resource use .github/workflows/ci.yml1-60
Parallel Test Runner: Tests run with per-file isolation by spawning separate python -m pytest <file> subprocesses, wrapped in the scripts/run_tests.sh script. This ensures no state leakage or concurrency issues. The tests are sharded across multiple slices for parallel execution .github/workflows/tests.yml104-108
Matrix Slicing with Duration Balancing: A generate job computes balanced test slices using a Longest Processing Time (LPT) algorithm implemented in scripts/run_tests_parallel.py. This dynamically splits tests across slices to minimize overall test duration variance and reduce CI run-time .github/workflows/tests.yml19-47
Duration Caching: To improve slice balancing over time, test durations from completed jobs are cached in test_durations.json, restored at test generation to inform slicing, and merged after successful runs on the main branch to keep the cache updated .github/workflows/tests.yml30-166
Dependency Reproducibility: The Python environment setup in CI uses uv sync --locked to reproduce the exact pinned dependency graph as defined in uv.lock. This promotes deterministic builds and prevents dependency drift .github/workflows/tests.yml90-94
Credential Isolation: Environment variables for cloud API keys (OPENAI_API_KEY, OPENROUTER_API_KEY, NOUS_API_KEY) are explicitly cleared in test jobs to prevent accidental live API usage during automated test runs .github/workflows/tests.yml117-121
Hermes Agent implements a focused supply-chain vulnerability audit with GitHub Actions named supply-chain-audit.yml. The audit checks for high-confidence indicators of malicious or risky code changes in pull requests:
| Check Type | Logic & Implementation | Rationale |
|---|---|---|
| .pth File Audit | Detects added/modified *.pth files via git diff (.pth files auto-exec on Python startup) .github/workflows/supply-chain-audit.yml87-98 | Avoid execution of hidden malicious code on interpreter startup. |
| Base64 + exec/eval | Searches for lines with both base64 decoding and exec() or eval() calls as a single pattern, a known stealth payload signature .github/workflows/supply-chain-audit.yml103-114 | High-signal marker of hidden credential stealing or arbitrary code execution. |
| Obfuscated Subprocess | Detects subprocess calls whose arguments contain encoded obfuscations (base64/hex/chr calls) .github/workflows/supply-chain-audit.yml117-128 | Prevents binary payload execution disguised in source. |
| Install Hooks | Monitors setup.py, setup.cfg, sitecustomize.py, usercustomize.py, and __init__.pth additions/changes executed during install/startup .github/workflows/supply-chain-audit.yml131-151 | Averts injection attacks at package install time. |
| Exact Pinning Enforced | Dependency versions pinned exactly (==X.Y.Z) as a best practice in pyproject.toml to forestall silent dependency drift pyproject.toml24-37 | Prevents unreviewed upstream dependency updates potentially introducing vulnerabilities. |
| Windows Footguns Scan | Scans for known unsafe Python practices on Windows, like os.kill(pid,0), implicit encoding errors in file IO, etc. .github/workflows/lint.yml146-163 | Guards against platform-specific fatal errors or crashes. |
The audited results feed into aggregated review comments and gating workflows to prevent merging of suspicious code.
Sources: .github/workflows/ci.yml1-60 .github/workflows/tests.yml1-166 .github/workflows/supply-chain-audit.yml1-162 .github/workflows/lint.yml146-163 pyproject.toml24-37
Hermes Agent follows a Calendar Versioning (CalVer) scheme, for example v2026.7.7.2, encoding the release date and a micro-bump to distinguish multiple releases per day hermes_cli/__init__.py17-18 The release process is automated by the scripts/release.py script, which manages changelog generation, version bumping, contributor attribution, and pushing version tags to GitHub scripts/release.py1-93
Data Flow Explanation:
scripts/release.py modifies version declarations in hermes_cli/__init__.py (which declares __version__), pyproject.toml (project metadata), and the ACP manifest acp_registry/agent.json (for integrated client protocol versioning).Sources: scripts/release.py1-93 hermes_cli/__init__.py17-18 .github/workflows/deploy-site.yml1-45
Version Synchronization: The script ensures atomic consistency between the Python version string, the pyproject.toml metadata, and the ACP registry version lock. Any release bumps update all three in one transaction with git commits scripts/release.py30-41
Contributor Map: To accurately attribute changelogs, the script merges a legacy hardcoded map of Git emails to GitHub usernames (LEGACY_AUTHOR_MAP) with files in the contributors/emails/ directory containing one email per file, avoiding merge conflicts and enabling incremental updates without altering the legacy map scripts/release.py40-88 This map is used to resolve authorship when generating changelogs and release notes.
ACP Version Locking: The release process updates the Agent Client Protocol manifest (acp_registry/agent.json) locked to the version in pyproject.toml. This contract is validated by tests (e.g., tests/acp/test_registry_manifest.py) to ensure all releases move the manifest forward together, preserving compatibility scripts/release.py33-41
Hermes Agent employs a lazy dependency installation system to manage optional backends and reduce install-time bloat and supply chain fragility tools/lazy_deps.py1-90
| Feature | Behavior | Benefits |
|---|---|---|
Allowlist (LAZY_DEPS) | Only packages declared in the LAZY_DEPS dictionary can be lazily installed at runtime, which corresponds to optional extras such as inference providers (provider.anthropic), TTS engines (tts.mistral), and memory plugins (memory.honcho) tools/lazy_deps.py95-150 | Restricts runtime installs to vetted packages only, improving security and predictability. |
| Exact Version Pinning | Versions of lazy-installed backends are exactly pinned to match pyproject.toml extras, preventing version mismatches or unintended downgrades pyproject.toml24-37 | Avoids dependency version drift that could introduce subtle bugs or vulnerabilities. |
| Durable Target Venv Redirection | Runtime lazy installs write to a separate writable location (e.g., /opt/data/lazy-packages) appended to sys.path when the primary venv is sealed (such as in Docker images). This prevents a bad lazy install from breaking core Hermes functionality tools/lazy_deps.py29-44 | Ensures isolation of lazy-installed packages and maintains core agent health. |
PyPI: The project uses uv build for creating standard source and wheel distributions. The PyPI upload workflow (upload_to_pypi.yml) is triggered by release tags pushed by release.py pyproject.toml3-5
Docker: Docker images are built reproducibly using pinned dependencies locked in uv.lock. The Docker workflow tests and pushes images to Docker Hub on new release tags .github/workflows/docker.yml
Extras Exclusion: The pyproject.toml excludes lazy-installable extras from the [all] extra to prevent eager installs of heavy or platform-specific dependencies. This avoids install failures from quarantined or incompatible PyPI releases (e.g., matrix extra deferred to lazy install) pyproject.toml34-37
To prevent UnicodeEncodeError crashes on non-UTF-8 systems (like fresh Raspberry Pi installs or Windows services), the CLI enforces UTF-8 encoding on stdout and stderr with the _ensure_utf8 function invoked at import time hermes_cli/__init__.py21-92 This function attempts to reconfigure existing streams or re-open them as UTF-8 with error replacement, applying the minimal necessary patch early before any CLI output occurs.
Sources: tools/lazy_deps.py1-150 pyproject.toml3-37 .github/workflows/docker.yml hermes_cli/__init__.py21-92
The Skills Hub catalog aggregates metadata from the skills and optional-skills directories into a unified skills index skills-index.json consumed by the web dashboard .github/workflows/deploy-site.yml76-154 The build process attempts to reuse the latest healthy skills index artifact or the currently deployed index to conserve GitHub API rate limits, only rebuilding fully on manual request.
This integration ensures the Skills Hub stays fresh and reflects the comprehensive agent capabilities exposed via skill plugins.
Sources: .github/workflows/deploy-site.yml76-154
Contributor Audit: A dedicated contributor-check.yml workflow validates that new contributors are properly credited in the author map and ensures no accidental omissions in changelogs or source attribution .github/workflows/contributor-check.yml The scripts/contributor_audit.py script is responsible for performing this check.
Supply Chain Audit Workflow: The supply-chain-audit.yml runs automatically on pull requests impacting supply-chain relevant files to detect malicious code additions or suspicious patterns .github/workflows/supply-chain-audit.yml1-162
OSV Vulnerability Scanning: The project leverages osv-scanner.yml workflow to detect known vulnerabilities in dependencies via the OSV database, providing ongoing security monitoring .github/workflows/osv-scanner.yml
CI Review Comments and Gates: Review status and critical warnings from audits are aggregated by live comment bots and gate jobs to enforce maintainer intervention on suspicious changes .github/workflows/ci.yml150-160 The scripts/ci/assemble_review_comment.py and scripts/ci/live_comment.py scripts are used to manage these comments.
Sources: .github/workflows/contributor-check.yml scripts/contributor_audit.py .github/workflows/supply-chain-audit.yml1-162 .github/workflows/osv-scanner.yml .github/workflows/ci.yml150-160 scripts/ci/assemble_review_comment.py scripts/ci/live_comment.py
The Hermes Agent's CI/CD and release infrastructure is designed for robust, secure delivery of a rapidly evolving AI agent framework. Key features include:
This holistic system balances the demands of continuous improvement and security critical in an open, dynamic AI agent project.
Sources: scripts/release.py1-93 hermes_cli/__init__.py17-92 .github/workflows/ci.yml1-180 .github/workflows/tests.yml1-166 .github/workflows/supply-chain-audit.yml1-162 .github/workflows/lint.yml146-163 .github/workflows/deploy-site.yml35-156 tools/lazy_deps.py1-150 pyproject.toml1-126 scripts/contributor_audit.py scripts/ci/assemble_review_comment.py scripts/ci/live_comment.py
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.