From a71cc734dfe90537a91cb4dbbbe1698563e236a8 Mon Sep 17 00:00:00 2001 From: mo7al876any Date: Sat, 4 Jul 2026 04:13:29 +0300 Subject: [PATCH] docs(env): document the HERMES_WEBUI_* vars the code reads but no template listed .env.example listed 8 basic vars; the server reads ~30. Add the operator-facing ones with defaults from the code, grouped into Security, Reverse-proxy header trust, Uploads & limits, Onboarding, and Advanced integrations: PASSWORD, PASSKEY, SESSION_TTL, SECURE, COOKIE_NAME, ALLOWED_ORIGINS, TLS_CERT/KEY, CSP_CONNECT_EXTRA/FRAME_EXTRA, TRUST_FORWARDED_HOST/FOR/PROTO, ATTACHMENT_DIR, MAX_EXTRACTED_MB, FOLDER_ZIP_MAX_*, SLOW_REQUEST_SECONDS, SKIP_ONBOARDING, PREFILL_* hooks, EXTERNAL_NOTES_SOURCES, PLUGINS_DIR, GATEWAY_API_KEY, CLAUDE_PROJECTS_DIR, CODEX_HOME, WIKI_PATH. The Docker template notes each needs a compose environment: passthrough to take effect. Co-Authored-By: Claude Fable 5 --- .env.docker.example | 31 +++++++++++++++ .env.example | 96 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+) diff --git a/.env.docker.example b/.env.docker.example index a2349bdf8..d0db0ecc0 100644 --- a/.env.docker.example +++ b/.env.docker.example @@ -47,6 +47,37 @@ GID=1000 # the agent. # HERMES_WEBUI_PASSWORD=change-me-to-something-strong +# ────────────────────────────────────────────────────────────────────────── +# Additional security / networking / limit knobs — advanced +# ────────────────────────────────────────────────────────────────────────── +# The WebUI process reads more HERMES_WEBUI_* variables than the compose +# files forward by default. To use any of these in Docker, uncomment it here +# AND add a matching passthrough line under `environment:` in your compose +# file (e.g. `- HERMES_WEBUI_SESSION_TTL=${HERMES_WEBUI_SESSION_TTL:-}`). +# Full descriptions live in .env.example. +# +# Auth cookie lifetime in seconds (default 2592000 = 30 days): +# HERMES_WEBUI_SESSION_TTL=2592000 +# +# Force the Secure cookie flag when serving HTTPS via a reverse proxy: +# HERMES_WEBUI_SECURE=1 +# +# Allowed public origins (scheme required) when behind a reverse proxy: +# HERMES_WEBUI_ALLOWED_ORIGINS=https://myapp.example.com +# +# Trust reverse-proxy forwarded headers (only enable behind a proxy YOU run): +# HERMES_WEBUI_TRUST_FORWARDED_HOST=1 +# HERMES_WEBUI_TRUST_FORWARDED_FOR=1 +# HERMES_WEBUI_TRUST_FORWARDED_PROTO=1 +# +# Enable the passkey/WebAuthn login surface (default off): +# HERMES_WEBUI_PASSKEY=1 +# +# Archive extraction cap (MB) and "download folder as ZIP" caps: +# HERMES_WEBUI_MAX_EXTRACTED_MB=2048 +# HERMES_WEBUI_FOLDER_ZIP_MAX_MB=1024 +# HERMES_WEBUI_FOLDER_ZIP_MAX_FILES=50000 + # ────────────────────────────────────────────────────────────────────────── # Permission handling for bind-mounted .hermes — advanced # ────────────────────────────────────────────────────────────────────────── diff --git a/.env.example b/.env.example index 27cd9b3d9..fbd91735e 100644 --- a/.env.example +++ b/.env.example @@ -32,3 +32,99 @@ # Display name for the assistant in the UI (default: Hermes) # HERMES_WEBUI_BOT_NAME=Hermes + +# ── Security & remote access ───────────────────────────────────────────────── + +# Password for the login page. REQUIRED if you bind to anything other than +# 127.0.0.1 — without it, anyone who can reach the port can run commands. +# HERMES_WEBUI_PASSWORD=change-me-to-something-strong + +# Enable the passkey/WebAuthn login surface (default: off). +# Alternative: set `webui_passkey_enabled: true` in the profile's config.yaml. +# HERMES_WEBUI_PASSKEY=1 + +# Auth cookie lifetime in seconds (default: 2592000 = 30 days). +# Clamped to [60, 31536000]. Also settable as session_ttl_seconds in settings.json. +# HERMES_WEBUI_SESSION_TTL=2592000 + +# Force the Secure flag on auth cookies: 1/true or 0/false. +# Unset = auto-detect (direct TLS socket, or a trusted X-Forwarded-Proto). +# HERMES_WEBUI_SECURE=1 + +# Override the auth cookie name (default: derived internally). +# HERMES_WEBUI_COOKIE_NAME=hermes_webui_session + +# Extra allowed origins for CSRF/origin checks when serving behind a reverse +# proxy or on a public hostname. Comma-separated; each entry MUST include the +# scheme. Entries without a scheme are ignored with a warning. +# HERMES_WEBUI_ALLOWED_ORIGINS=https://myapp.example.com:8000 + +# Serve HTTPS directly (both must be set; otherwise plain HTTP). +# HERMES_WEBUI_TLS_CERT=/path/to/fullchain.pem +# HERMES_WEBUI_TLS_KEY=/path/to/privkey.pem + +# Extra sources appended to the Content-Security-Policy (space-separated). +# HERMES_WEBUI_CSP_CONNECT_EXTRA=https://api.example.com wss://api.example.com +# HERMES_WEBUI_CSP_FRAME_EXTRA=https://embed.example.com + +# ── Reverse-proxy header trust (opt-in; only enable behind a proxy YOU run) ─── +# By default these forwarded headers are NOT trusted, because any direct client +# could forge them. Enable (1/true/yes/on) only when a reverse proxy you control +# sets them. TRUST_FORWARDED_HOST: honor X-Forwarded-Host/X-Real-Host in origin +# checks. TRUST_FORWARDED_FOR: honor X-Forwarded-For for the client IP. +# TRUST_FORWARDED_PROTO: honor X-Forwarded-Proto for HTTPS detection. +# HERMES_WEBUI_TRUST_FORWARDED_HOST=1 +# HERMES_WEBUI_TRUST_FORWARDED_FOR=1 +# HERMES_WEBUI_TRUST_FORWARDED_PROTO=1 + +# ── Uploads & limits ───────────────────────────────────────────────────────── + +# Where chat attachments are stored (default: /attachments). +# Attachments are transient agent context, kept out of the workspace by default. +# HERMES_WEBUI_ATTACHMENT_DIR=~/.hermes/webui/attachments + +# Cap on total bytes an uploaded archive may expand to (zip-bomb guard). +# Default derives from the upload size limit; override in MB. +# HERMES_WEBUI_MAX_EXTRACTED_MB=2048 + +# Caps for the "download folder as ZIP" feature in the workspace browser. +# HERMES_WEBUI_FOLDER_ZIP_MAX_MB=1024 +# HERMES_WEBUI_FOLDER_ZIP_MAX_FILES=50000 + +# Requests slower than this many seconds get a stack-dump diagnostic in the log +# (default: 5.0; set 0 to log every request's timing). +# HERMES_WEBUI_SLOW_REQUEST_SECONDS=5.0 + +# ── Onboarding ─────────────────────────────────────────────────────────────── + +# Skip the first-run onboarding wizard entirely. +# HERMES_WEBUI_SKIP_ONBOARDING=1 + +# ── Advanced integrations ──────────────────────────────────────────────────── + +# Script whose stdout prefills new-session context (legacy generic hook; the +# WebUI dynamic-recall hook in config.yaml takes precedence when configured). +# HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT=/path/to/script +# HERMES_WEBUI_PREFILL_MESSAGES_SCRIPT_TIMEOUT=10 +# HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS=20000 + +# Extra sources for the notes drawer (see docs for the expected format). +# HERMES_WEBUI_EXTERNAL_NOTES_SOURCES= + +# Directory scanned for WebUI plugins (default: ~/.hermes/plugins). +# HERMES_WEBUI_PLUGINS_DIR=~/.hermes/plugins + +# API key used when polling the Hermes gateway health endpoint. +# HERMES_WEBUI_GATEWAY_API_KEY= + +# Override the Claude Code projects directory scanned by the CLI session +# bridge (default: auto-discovered ~/.claude/projects). +# HERMES_WEBUI_CLAUDE_PROJECTS_DIR=~/.claude/projects + +# Override the Codex CLI home scanned by the CLI session bridge and model +# catalog merge (default: ~/.codex). +# CODEX_HOME=~/.codex + +# Path to the LLM wiki root shown in the wiki panel (default: resolved from +# HERMES_HOME's wiki env file). +# WIKI_PATH=/path/to/wiki