hermes-webui/.env.example

# Hermes Web UI -- local machine config template
# Copy this to .env and fill in your values.
# start.sh sources .env automatically if present.
# All values are optional -- auto-discovery will fill in anything left blank.

# Path to your hermes-agent checkout (the repo that contains run_agent.py)
# HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent

# Python executable to use (defaults to the agent venv if found)
# HERMES_WEBUI_PYTHON=/path/to/python

# Bind address (default: 127.0.0.1 -- loopback only, safe default)
# HERMES_WEBUI_HOST=127.0.0.1

# Port to listen on (default: 8787)
# HERMES_WEBUI_PORT=8787

# Where to store sessions, workspaces, and other state (default: ~/.hermes/webui)
# HERMES_WEBUI_STATE_DIR=~/.hermes/webui

# Default workspace directory shown on first launch
# HERMES_WEBUI_DEFAULT_WORKSPACE=~/workspace

# Optional model override. Leave unset to use the active Hermes provider default.
# HERMES_WEBUI_DEFAULT_MODEL=

# Base directory for all Hermes state (affects all paths above if set)
# HERMES_HOME=~/.hermes

# Path to your Hermes config.yaml (for toolsets and model config)
# HERMES_CONFIG_PATH=~/.hermes/config.yaml

# 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

# ── Trusted-header auth / reverse-proxy SSO (opt-in; OFF by default) ──────────
# Delegate authentication to a reverse proxy you run (Authelia, oauth2-proxy,
# corporate SSO, …) that authenticates the user and forwards their identity in a
# header. When HERMES_WEBUI_TRUSTED_AUTH_HEADER is set, the WebUI treats a request
# as that identity — but ONLY when the request's un-spoofable raw socket peer is
# an allowlisted proxy (HERMES_WEBUI_TRUSTED_PROXY_CIDRS below). With no header
# set, this path is disabled and normal password/passkey auth applies.
#
# ⚠️ SECURITY: HERMES_WEBUI_TRUSTED_PROXY_CIDRS MUST list the EXACT IP(s) of your
# proxy — e.g. 10.0.0.5/32 or 127.0.0.1/32. NEVER use 0.0.0.0/0 or a broad range:
# any client whose peer IP falls in the range could forge the identity header and
# log in as anyone. If the allowlist is empty/malformed, the header is ignored
# (fails closed). Loopback is trusted by default. Set the CIDR to your proxy only.
# HERMES_WEBUI_TRUSTED_AUTH_HEADER=Remote-User
# HERMES_WEBUI_TRUSTED_PROXY_CIDRS=10.0.0.5/32
# Optional: map a forwarded groups header to WebUI profiles (JSON object), and a
# logout URL to redirect to after clearing the local session (SSO single-logout).
# HERMES_WEBUI_TRUSTED_GROUPS_HEADER=Remote-Groups
# HERMES_WEBUI_GROUP_PROFILE_MAP={"admins":"default","team-a":"projecta"}
# HERMES_WEBUI_TRUSTED_AUTH_LOGOUT_URL=https://sso.example.com/logout

# ── Uploads & limits ─────────────────────────────────────────────────────────

# Where chat attachments are stored (default: <state dir>/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=5
# HERMES_WEBUI_PREFILL_CONTEXT_MAX_CHARS=12000

# 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