gortium/compose
1
1
Fork 0
Code Issues Pull Requests 18 Actions Packages Projects Releases Wiki Activity

fix: Matrix bridge ModuleNotFoundError - install deps to venv with persistence #2

Merged
gortium merged 5 commits from fix/matrix-bridge-dependencies into master 2026-05-20 18:47:30 +00:00
Conversation 1 Commits 5 Files Changed 1 +3 -3
Hermes commented 2026-04-29 02:35:06 +00:00
Collaborator
Copy Link

Problem

Users connecting via Matrix bridge receive this error:

Sorry, I encountered an error (ModuleNotFoundError). No module named 'openai'

The Hermes gateway fails to start because required Python dependencies (openai, matrix-nio) are not installed in the runtime environment.

Root Cause Analysis

The Hermes agent uses an isolated virtual environment at /opt/hermes/.venv for dependency management. The previous compose configuration had two critical issues:

  1. Wrong installation target: The entrypoint installed packages to the system Python (pip install), but the gateway runs from the isolated venv (/opt/hermes/.venv/bin/hermes)

  2. Ephemeral venv: Even if packages were installed to the venv correctly, the venv directory was not persisted. Container restarts would wipe all installed dependencies.

Solution

1. Install to correct environment using uv

Changed entrypoint from:

command: "sh -c 'pip install openai matrix-nio[encryption] -q && hermes gateway run'"

To:

command: "sh -c '/opt/hermes/.venv/bin/uv pip install openai matrix-nio[encryption] --system -q && /opt/hermes/.venv/bin/hermes gateway run'"

Why uv? Hermes uses astral-sh's uv as the modern Python package manager (faster, more reliable than pip).

Why --system? Required flag when installing into an active virtual environment from a script context.

Why matrix-nio[encryption]? Hermes uses the matrix-nio asyncio SDK (not mautrix). The [encryption] extra enables Olm protocol for E2EE room support.

2. Persist venv to host storage

Added new volume mount:

- /mnt/HoardingCow_docker_data/Hermes/venv:/opt/hermes/.venv

This ensures installed packages survive container restarts and rebuilds.

Testing & Verification

After deployment, verify with:

docker exec hermes /opt/hermes/.venv/bin/python -c "import openai, nio; print('OK')"

Expected output: OK

Then test Matrix connection - the ModuleNotFoundError should be resolved.

Deployment Notes

This change requires container recreation (not just restart). On NixOS with declarative Docker stacks:

sudo nixos-rebuild switch --flake .#lazyworkhorse

The reloadTriggers mechanism in docker_manager.nix detects the compose.yml hash change and recreates the container automatically.

Related

  • Issue: gortium/infra#4
  • Fixes: ModuleNotFoundError preventing Matrix bridge connectivity
  • Infrastructure: /opt/data/infra/assets/compose/ai/compose.yml
## Problem Users connecting via Matrix bridge receive this error: ``` Sorry, I encountered an error (ModuleNotFoundError). No module named 'openai' ``` The Hermes gateway fails to start because required Python dependencies (`openai`, `matrix-nio`) are not installed in the runtime environment. ## Root Cause Analysis The Hermes agent uses an **isolated virtual environment** at `/opt/hermes/.venv` for dependency management. The previous compose configuration had two critical issues: 1. **Wrong installation target**: The entrypoint installed packages to the system Python (`pip install`), but the gateway runs from the isolated venv (`/opt/hermes/.venv/bin/hermes`) 2. **Ephemeral venv**: Even if packages were installed to the venv correctly, the venv directory was not persisted. Container restarts would wipe all installed dependencies. ## Solution ### 1. Install to correct environment using `uv` Changed entrypoint from: ```yaml command: "sh -c 'pip install openai matrix-nio[encryption] -q && hermes gateway run'" ``` To: ```yaml command: "sh -c '/opt/hermes/.venv/bin/uv pip install openai matrix-nio[encryption] --system -q && /opt/hermes/.venv/bin/hermes gateway run'" ``` **Why `uv`?** Hermes uses astral-sh's `uv` as the modern Python package manager (faster, more reliable than pip). **Why `--system`?** Required flag when installing into an active virtual environment from a script context. **Why `matrix-nio[encryption]`?** Hermes uses the `matrix-nio` asyncio SDK (not mautrix). The `[encryption]` extra enables Olm protocol for E2EE room support. ### 2. Persist venv to host storage Added new volume mount: ```yaml - /mnt/HoardingCow_docker_data/Hermes/venv:/opt/hermes/.venv ``` This ensures installed packages survive container restarts and rebuilds. ## Testing & Verification After deployment, verify with: ```bash docker exec hermes /opt/hermes/.venv/bin/python -c "import openai, nio; print('OK')" ``` Expected output: `OK` Then test Matrix connection - the ModuleNotFoundError should be resolved. ## Deployment Notes This change requires container recreation (not just restart). On NixOS with declarative Docker stacks: ```bash sudo nixos-rebuild switch --flake .#lazyworkhorse ``` The `reloadTriggers` mechanism in `docker_manager.nix` detects the compose.yml hash change and recreates the container automatically. ## Related - Issue: https://code.lazyworkhorse.net/gortium/infra/issues/4 - Fixes: ModuleNotFoundError preventing Matrix bridge connectivity - Infrastructure: /opt/data/infra/assets/compose/ai/compose.yml
Hermes added 1 commit 2026-04-29 02:35:06 +00:00
fix: Add openai and matrix-nio dependencies for Hermes Matrix bridge f9afd79f3e
Hermes added 1 commit 2026-04-29 02:43:44 +00:00
fix: Correct OPENROUTER_API_KEY variable name a404f5e2c4
Hermes changed title from fix: Add openai and matrix-nio dependencies for Hermes Matrix bridge to fix: Matrix bridge ModuleNotFoundError - install deps to venv with persistence 2026-04-29 02:58:03 +00:00
Hermes added 1 commit 2026-04-29 03:35:06 +00:00
fix: use mautrix[encryption] instead of matrix-nio for Matrix bridge 2aab06cc1a 
The Hermes Matrix gateway uses the mautrix SDK, not matrix-nio.
This fixes E2EE support by installing the correct library.

Refs: PR #2
gortium commented 2026-05-16 11:14:29 +00:00
Owner
Copy Link

@Hermes this rp need to be updated. Dont create a new persistent volume. Instead, add the requirements to de custom hermes dockerfile we have now.

@Hermes this rp need to be updated. Dont create a new persistent volume. Instead, add the requirements to de custom hermes dockerfile we have now.
Hermes added 2 commits 2026-05-20 18:42:23 +00:00
Merge pull request #2: fix: Matrix bridge ModuleNotFoundError - install deps to venv with persistence dea1429a5d 
# Conflicts:
#	ai/compose.yml
Merge master into fix/matrix-bridge-dependencies to resolve conflicts
Some checks failed
Build Hermes agent / build (pull_request) Has been cancelled
Details
Build ollama (gfx906) / build (pull_request) Has been cancelled
Details
2ff99b1f57
gortium merged commit 35aa466e87 into master 2026-05-20 18:47:30 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Hermes gortium
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: gortium/compose#2
No description provided.
Delete Branch "fix/matrix-bridge-dependencies"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?