mirror of https://github.com/nesquena/hermes-webui.git synced 2026-07-08 16:52:02 +00:00

Files

T

nanw 4b202d1267 fix(docker): exclude .playwright from rsync staging to avoid error 23

The agent source at /opt/hermes inside the container may contain a
.playwright/ directory with browser dependency files that have restricted
permissions. rsync fails with exit code 23 when attempting to read them,
which kills the container build ("Failed to stage hermes-agent source").

- Add --exclude=.playwright to rsync in docker_init.bash
- Add rm -rf .playwright to cp -a fallback path for symmetry
- Update test_docker_init_excludes_egg_info_during_staging to assert
  both the rsync --exclude and a broad .playwright presence check
- Add a brief note in AGENTS.md Contribution style about mirroring
  directory exclusions in both rsync and cp paths

Fixes #5315

2026-07-01 14:21:09 +08:00

4.1 KiB

Raw Permalink Blame History

Agent instructions for Hermes WebUI

This file is the shared entry point for AI assistants working in this repository. Keep it project-specific and safe to publish. Do not put personal machine setup, private network details, credentials, tokens, or local-only workflow notes here.

Read first

Before making changes, read:

README.md
CONTRIBUTING.md
docs/CONTRACTS.md
CHANGELOG.md

For architecture, testing, or setup work, also read the matching reference:

ARCHITECTURE.md for design constraints and current module layout
TESTING.md for local verification commands and manual test guidance
docs/onboarding.md for first-run onboarding behavior
docs/troubleshooting.md for diagnostic flows
docs/rfcs/README.md for larger RFCs and state/durability contracts

For UI or UX work, read docs/UIUX-GUIDE.md and DESIGN.md before changing layout, interaction flow, themes, chat rendering, or composer chrome.

Onboarding and reinstall support

If the task involves install, reinstall, bootstrap, first-run onboarding, provider setup, local model server setup, Docker onboarding, WSL onboarding, or support for a failed first run, read docs/onboarding-agent-checklist.md before running commands or inspecting logs.

Follow that checklist's safety rules:

use isolated HERMES_HOME and HERMES_WEBUI_STATE_DIR for trials unless the human explicitly asks to use real state
do not delete or overwrite a real ~/.hermes directory without explicit approval
do not print API keys, OAuth tokens, cookies, full .env files, full auth.json files, or password hashes
collect non-secret status and log evidence before recommending a fix

Contribution style

Keep one logical change per PR; split unrelated refactors or cleanup.
Read docs/CONTRACTS.md and the linked contract/RFC for the touched subsystem before editing.
For local pytest runs, use ./scripts/test.sh instead of bare python3, python -m pytest, or pytest. The script creates/uses the repo .venv, pins execution to Python 3.11-3.13, and installs missing dev test dependencies. HERMES_WEBUI_TEST_PYTHON selects the supported base interpreter used to create or rebuild .venv; it must not install test dependencies into a system/Homebrew interpreter directly. If a direct pytest invocation reports an unsupported interpreter, rerun through ./scripts/test.sh before debugging product code.
Prefer the existing Python + vanilla JavaScript structure. Do not add dependencies, build tools, frameworks, or long-lived processes without clear justification and a rollback story.
Update docs when changing setup, onboarding, runtime behavior, architecture, testing guidance, or user-facing workflows.
Do not edit CHANGELOG.md in ordinary contributor PRs. The release workflow owns changelog updates through release commits. If a change is release-note worthy, include concise release-note wording in the PR body instead.
For UI or UX changes, include before/after evidence and test relevant desktop, narrow, and mobile states.
For behavior changes, add or update automated tests where practical and list the manual verification performed.
For runtime, streaming, recovery, replay, compression, or sidebar metadata changes, name the state layer being mutated and prove the relevant invariant.
For Docker build changes in docker_init.bash, mirror directory exclusions in both the rsync and cp -a paths — /opt/hermes may contain subdirectories with restricted permissions (e.g. .playwright/).

Local state and secrets

Hermes WebUI can read and write real agent state, sessions, workspaces, credentials, and cron data. Treat local validation as potentially destructive unless you have confirmed the active state directories.

Prefer isolated trial state for experiments:

HERMES_HOME=/tmp/hermes-webui-agent-home \
HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
HERMES_WEBUI_PORT=8789 \
python3 bootstrap.py

Do not include private machine instructions in this tracked file. Use a git-ignored local note for personal workflow details.