Initial Commit

.env.example

@@ -0,0 +1,534 @@
+# Hermes Agent Environment Configuration
+# Copy this file to .env and fill in your API keys
+
+# HERMES_DASHBOARD_PASSWORD=
+# HERMES_DASHBOARD_USERNAME=
+
+# =============================================================================
+# LLM PROVIDER (Fireworks AI)
+# =============================================================================
+# Get your key at: https://app.fireworks.ai/settings/users/api-keys
+# Address models directly by catalog ID, e.g.
+#   accounts/fireworks/models/kimi-k2p6, accounts/fireworks/models/glm-5p2
+# FIREWORKS_API_KEY=
+# =============================================================================
+# LLM PROVIDER (OpenRouter)
+# =============================================================================
+# OpenRouter provides access to many models through one API
+# All LLM calls go through OpenRouter - no direct provider keys needed
+# Get your key at: https://openrouter.ai/keys
+# OPENROUTER_API_KEY=
+
+# Default model is configured in ~/.hermes/config.yaml (model.default).
+# Use 'hermes model' or 'hermes setup' to change it.
+# LLM_MODEL is no longer read from .env — this line is kept for reference only.
+# LLM_MODEL=anthropic/claude-opus-4.6
+
+# =============================================================================
+# LLM PROVIDER (NovitaAI)
+# =============================================================================
+# NovitaAI — 90+ models, pay-per-use
+# Get your key at: https://novita.ai/settings/key-management
+# NOVITA_API_KEY=
+# NOVITA_BASE_URL=https://api.novita.ai/openai/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Google AI Studio / Gemini)
+# =============================================================================
+# Native Gemini API via Google's OpenAI-compatible endpoint.
+# Get your key at: https://aistudio.google.com/app/apikey
+# GOOGLE_API_KEY=your_google_ai_studio_key_here
+# GEMINI_API_KEY=your_gemini_key_here  # alias for GOOGLE_API_KEY
+# Optional base URL override (default: Google's OpenAI-compatible endpoint)
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+
+# =============================================================================
+# LLM PROVIDER (Ollama Cloud)
+# =============================================================================
+# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.
+# Get your key at: https://ollama.com/settings
+# OLLAMA_API_KEY=your_ollama_key_here
+# Optional base URL override (default: https://ollama.com/v1)
+# OLLAMA_BASE_URL=https://ollama.com/v1
+
+# =============================================================================
+# LLM PROVIDER (z.ai / GLM)
+# =============================================================================
+# z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)
+# Get your key at: https://z.ai or https://open.bigmodel.cn
+# GLM_API_KEY=
+# GLM_BASE_URL=https://api.z.ai/api/paas/v4  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Kimi / Moonshot)
+# =============================================================================
+# Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.)
+# Get your key at: https://platform.kimi.ai (Kimi Code console)
+# Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.
+# Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.
+# KIMI_API_KEY=
+# KIMI_BASE_URL=https://api.kimi.com/coding/v1  # Default for sk-kimi- keys
+# KIMI_BASE_URL=https://api.moonshot.ai/v1      # For legacy Moonshot keys
+# KIMI_BASE_URL=https://api.moonshot.cn/v1       # For Moonshot China keys
+# KIMI_CN_API_KEY=                               # Dedicated Moonshot China key
+
+# =============================================================================
+# LLM PROVIDER (Arcee AI)
+# =============================================================================
+# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)
+# Get an Arcee key at: https://chat.arcee.ai/
+# ARCEEAI_API_KEY=
+# ARCEE_BASE_URL=                                 # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (MiniMax)
+# =============================================================================
+# MiniMax provides access to MiniMax models (global endpoint)
+# Get your key at: https://www.minimax.io
+# MINIMAX_API_KEY=
+# MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL
+
+# MiniMax China endpoint (for users in mainland China)
+# MINIMAX_CN_API_KEY=
+# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Zen)
+# =============================================================================
+# OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)
+# Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth
+# OPENCODE_ZEN_API_KEY=
+# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Go)
+# =============================================================================
+# OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)
+# $10/month subscription. Get your key at: https://opencode.ai/auth
+# OPENCODE_GO_API_KEY=
+
+# =============================================================================
+# LLM PROVIDER (Hugging Face Inference Providers)
+# =============================================================================
+# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.
+# Free tier included ($0.10/month), no markup on provider rates.
+# Get your token at: https://huggingface.co/settings/tokens
+# Required permission: "Make calls to Inference Providers"
+# HF_TOKEN=
+# HF_BASE_URL=https://router.huggingface.co/v1  # Override default base URL
+# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL
+
+# DeepInfra — 100+ top open models, pay-per-use.
+# Get your key at: https://deepinfra.com/dash/api_keys
+# DEEPINFRA_API_KEY=
+
+# =============================================================================
+# LLM PROVIDER (Qwen OAuth)
+# =============================================================================
+# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).
+# No API key needed — credentials come from ~/.qwen/oauth_creds.json.
+# Optional base URL override:
+# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1
+
+# =============================================================================
+# LLM PROVIDER (Xiaomi MiMo)
+# =============================================================================
+# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).
+# Get your key at: https://platform.xiaomimimo.com
+# XIAOMI_API_KEY=your_key_here
+# Optional base URL override:
+# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1
+
+# =============================================================================
+# LLM PROVIDER (Upstage Solar)
+# =============================================================================
+# Upstage provides access to Upstage Solar models.
+# Get your key at: https://console.upstage.ai/api-keys
+# UPSTAGE_API_KEY=your_key_here
+# Optional base URL override:
+# UPSTAGE_BASE_URL=https://api.upstage.ai/v1
+
+# =============================================================================
+# TOOL API KEYS
+# =============================================================================
+
+# Exa API Key - AI-native web search and contents
+# Get at: https://exa.ai
+# EXA_API_KEY=
+
+# Parallel API Key - AI-native web search and extract
+# Get at: https://parallel.ai
+# PARALLEL_API_KEY=
+
+# Firecrawl API Key - Web search, extract, and crawl
+# Get at: https://firecrawl.dev/
+# FIRECRAWL_API_KEY=
+
+
+# FAL.ai API Key - Image generation
+# Get at: https://fal.ai/
+# FAL_KEY=
+
+# Honcho - Cross-session AI-native user modeling (optional)
+# Builds a persistent understanding of the user across sessions and tools.
+# Get at: https://app.honcho.dev
+# Also requires ~/.honcho/config.json with enabled=true (see README).
+# HONCHO_API_KEY=
+
+# =============================================================================
+# HYPERLIQUID OPTIONAL SKILL
+# =============================================================================
+# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid
+#
+# Hyperliquid API base URL override
+# Default: https://api.hyperliquid.xyz
+# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
+#
+# Default address for account-level commands like state, fills, orders, and review
+# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000
+
+# =============================================================================
+# TERMINAL TOOL CONFIGURATION
+# =============================================================================
+# Backend type: "local", "singularity", "docker", "modal", or "ssh"
+# Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
+# Use 'hermes setup' or 'hermes config set terminal.backend docker' to change.
+# Supported: local, docker, singularity, modal, ssh
+#
+# Only override here if you need to force a backend without touching config.yaml:
+# TERMINAL_ENV=local
+
+# Override the container runtime binary (e.g. to use Podman instead of Docker).
+# Useful on systems where Docker's storage driver is broken or unavailable.
+# HERMES_DOCKER_BINARY=/usr/local/bin/podman
+
+# Container images (for singularity/docker/modal backends)
+# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
+TERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+
+
+# Working directory for terminal commands
+# For local backend: "." means current directory (resolved automatically)
+# For remote backends (ssh/docker/modal/singularity): use an absolute path
+#   INSIDE the target environment, or leave unset for the backend's default
+#   (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.
+# Usually managed by config.yaml (terminal.cwd) — uncomment to override
+# TERMINAL_CWD=.
+
+# Default command timeout in seconds
+TERMINAL_TIMEOUT=60
+
+# Cleanup inactive environments after this many seconds
+TERMINAL_LIFETIME_SECONDS=300
+
+# =============================================================================
+# SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh)
+# =============================================================================
+# Run terminal commands on a remote server via SSH.
+# Agent code stays on your machine, commands execute remotely.
+#
+# SECURITY BENEFITS:
+# - Agent cannot read your .env file (API keys protected)
+# - Agent cannot modify its own code
+# - Remote server acts as isolated sandbox
+# - Can safely configure passwordless sudo on remote
+#
+# TERMINAL_SSH_HOST=192.168.1.100
+# TERMINAL_SSH_USER=agent
+# TERMINAL_SSH_PORT=22
+# TERMINAL_SSH_KEY=~/.ssh/id_rsa
+
+# =============================================================================
+# SUDO SUPPORT (works with ALL terminal backends)
+# =============================================================================
+# If set, enables sudo commands by piping password via `sudo -S`.
+# Works with: local, docker, singularity, modal, and ssh backends.
+# 
+# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.
+# 
+# ALTERNATIVES:
+# - For SSH backend: Configure passwordless sudo on the remote server
+# - For containers: Run as root inside the container (no sudo needed)
+# - For local: Configure /etc/sudoers for specific commands
+# - For CLI: Leave unset - you'll be prompted interactively with 45s timeout
+#
+# SUDO_PASSWORD=your_password_here
+
+# =============================================================================
+# MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal)
+# =============================================================================
+# Modal uses CLI authentication, not environment variables.
+# Run: pip install modal && modal setup
+# This will authenticate via browser and store credentials locally.
+# No API key needed in .env - Modal handles auth automatically.
+
+# =============================================================================
+# BROWSER TOOL CONFIGURATION (agent-browser + Browserbase)
+# =============================================================================
+# Browser automation requires Browserbase cloud service for remote browser execution.
+# This allows the agent to navigate websites, fill forms, and extract information.
+#
+# STEALTH MODES:
+# - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving)
+# - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only)
+
+# Browserbase API Key - Cloud browser execution
+# Get at: https://browserbase.com/
+# BROWSERBASE_API_KEY=
+
+# Browserbase Project ID - From your Browserbase dashboard
+# BROWSERBASE_PROJECT_ID=
+
+# Enable residential proxies for better CAPTCHA solving (default: true)
+# Routes traffic through residential IPs, significantly improves success rate
+BROWSERBASE_PROXIES=true
+
+# Enable advanced stealth mode (default: false, requires Scale Plan)
+# Uses custom Chromium build to avoid bot detection altogether
+BROWSERBASE_ADVANCED_STEALTH=false
+
+# Browser engine for local mode (default: auto = Chrome)
+# "auto"       — use Chrome (don't pass --engine flag)
+# "lightpanda" — use Lightpanda (1.3-5.8x faster navigation, no screenshots)
+# "chrome"     — explicitly request Chrome
+# Requires agent-browser v0.25.3+. Lightpanda commands that fail or return
+# empty results are automatically retried with Chrome.
+# Also configurable via browser.engine in config.yaml.
+# AGENT_BROWSER_ENGINE=auto
+
+# Browser session timeout in seconds (default: 300)
+# Sessions are cleaned up after this duration of inactivity
+BROWSER_SESSION_TIMEOUT=300
+
+# Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min)
+# Browser sessions are automatically closed after this period of no activity
+BROWSER_INACTIVITY_TIMEOUT=120
+
+# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.
+# Hermes auto-injects "--no-sandbox,--disable-dev-shm-usage" when it detects root
+# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,
+# many container images), so leave this unset unless you need extra flags.
+# Setting this disables the auto-injection.
+# AGENT_BROWSER_ARGS=--no-sandbox
+
+# Camofox local anti-detection browser (Camoufox-based Firefox).
+# Set CAMOFOX_URL to route the browser tools through a local Camofox server
+# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.
+# CAMOFOX_URL=http://localhost:9377
+
+# Externally managed Camofox sessions — when another app owns the visible
+# Camofox browser, set these so Hermes shares the same userId/profile instead
+# of creating its own isolated session.
+# CAMOFOX_USER_ID=
+# CAMOFOX_SESSION_KEY=
+# Set to true to reuse an already-open Camofox tab for this identity before
+# creating a new one (useful for gateway restarts).
+# CAMOFOX_ADOPT_EXISTING_TAB=false
+
+# =============================================================================
+# SESSION LOGGING
+# =============================================================================
+# Session trajectories are automatically saved to logs/ directory
+# Format: logs/session_YYYYMMDD_HHMMSS_UUID.json
+# Contains full conversation history in trajectory format for debugging/replay
+
+# =============================================================================
+# VOICE TRANSCRIPTION & OPENAI TTS
+# =============================================================================
+# Required for voice message transcription (Whisper) and OpenAI TTS voices.
+# Uses OpenAI's API directly (not via OpenRouter).
+# Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.
+# Get at: https://platform.openai.com/api-keys
+# VOICE_TOOLS_OPENAI_KEY=
+
+# =============================================================================
+# SLACK INTEGRATION
+# =============================================================================
+# Slack Bot Token - From Slack App settings (OAuth & Permissions)
+# Get at: https://api.slack.com/apps
+# SLACK_BOT_TOKEN=xoxb-...
+
+# Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings)
+# SLACK_APP_TOKEN=xapp-...
+
+# Slack allowed users (comma-separated Slack user IDs)
+# SLACK_ALLOWED_USERS=
+
+# =============================================================================
+# TELEGRAM INTEGRATION
+# =============================================================================
+# Telegram Bot Token - From @BotFather (https://t.me/BotFather)
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_ALLOWED_USERS=                  # Comma-separated user IDs
+# TELEGRAM_HOME_CHANNEL=                   # Default chat for cron delivery
+# TELEGRAM_HOME_CHANNEL_NAME=              # Display name for home channel
+# TELEGRAM_CRON_THREAD_ID=                 # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode
+
+# Webhook mode (optional — for cloud deployments like Fly.io/Railway)
+# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.
+# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
+# TELEGRAM_WEBHOOK_PORT=8443
+# TELEGRAM_WEBHOOK_SECRET=                 # Recommended for production
+
+# WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)
+# WHATSAPP_ENABLED=false
+# WHATSAPP_ALLOWED_USERS=15551234567
+
+# Email (IMAP/SMTP — send and receive emails as Hermes)
+# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords
+# EMAIL_ADDRESS=hermes@gmail.com
+# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx
+# EMAIL_IMAP_HOST=imap.gmail.com
+# EMAIL_IMAP_PORT=993
+# EMAIL_SMTP_HOST=smtp.gmail.com
+# EMAIL_SMTP_PORT=587
+# EMAIL_POLL_INTERVAL=15
+# EMAIL_ALLOWED_USERS=your@email.com
+# EMAIL_HOME_ADDRESS=your@email.com
+
+# Gateway-wide: allow ALL users without an allowlist (default: false = deny)
+# Only set to true if you intentionally want open access.
+# GATEWAY_ALLOW_ALL_USERS=false
+
+# =============================================================================
+# RESPONSE PACING
+# =============================================================================
+# Human-like delays between message chunks on messaging platforms.
+# Makes the bot feel less robotic.
+# HERMES_HUMAN_DELAY_MODE=off     # off | natural | custom
+# HERMES_HUMAN_DELAY_MIN_MS=800   # Min delay in ms (custom mode)
+# HERMES_HUMAN_DELAY_MAX_MS=2500  # Max delay in ms (custom mode)
+
+# =============================================================================
+# DEBUG OPTIONS
+# =============================================================================
+WEB_TOOLS_DEBUG=false
+VISION_TOOLS_DEBUG=false
+MOA_TOOLS_DEBUG=false
+IMAGE_TOOLS_DEBUG=false
+
+# =============================================================================
+# CONTEXT COMPRESSION (Auto-shrinks long conversations)
+# =============================================================================
+# When conversation approaches model's context limit, middle turns are
+# automatically summarized to free up space.
+#
+# Context compression is configured in ~/.hermes/config.yaml under compression:
+# CONTEXT_COMPRESSION_ENABLED=true        # Enable auto-compression (default: true)
+# CONTEXT_COMPRESSION_THRESHOLD=0.85      # Compress at 85% of context limit
+# Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)
+
+# =============================================================================
+# SKILLS HUB (GitHub integration for skill search/install/publish)
+# =============================================================================
+
+# GitHub Personal Access Token — for higher API rate limits on skill search/install
+# Get at: https://github.com/settings/tokens (Fine-grained recommended)
+# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+
+# GitHub App credentials (optional — for bot identity on PRs)
+# GITHUB_APP_ID=
+# GITHUB_APP_PRIVATE_KEY_PATH=
+# GITHUB_APP_INSTALLATION_ID=
+
+# Groq API key (free tier — used for Whisper STT in voice mode)
+# GROQ_API_KEY=
+
+# ElevenLabs API key (cloud STT/TTS — Scribe transcription)
+# ELEVENLABS_API_KEY=
+
+# =============================================================================
+# STT PROVIDER SELECTION
+# =============================================================================
+# Default STT provider is "local" (faster-whisper) — runs on your machine, no API key needed.
+# Install with: pip install faster-whisper
+# Model downloads automatically on first use (~150 MB for "base").
+# To use cloud providers instead, set GROQ_API_KEY, VOICE_TOOLS_OPENAI_KEY, or ELEVENLABS_API_KEY above.
+# Provider priority: local > groq > openai > mistral > xai > elevenlabs
+# Configure in config.yaml: stt.provider: local | groq | openai | mistral | xai | elevenlabs
+
+# =============================================================================
+# STT ADVANCED OVERRIDES (optional)
+# =============================================================================
+# Override default STT models per provider (normally set via stt.model in config.yaml)
+# STT_GROQ_MODEL=whisper-large-v3-turbo
+# STT_OPENAI_MODEL=whisper-1
+# STT_ELEVENLABS_MODEL=scribe_v2
+
+# Override STT provider endpoints (for proxies or self-hosted instances)
+# GROQ_BASE_URL=https://api.groq.com/openai/v1
+# STT_OPENAI_BASE_URL=https://api.openai.com/v1
+# ELEVENLABS_STT_BASE_URL=https://api.elevenlabs.io/v1
+
+# =============================================================================
+# MICROSOFT TEAMS INTEGRATION
+# =============================================================================
+# Register a Bot in Azure: https://dev.botframework.com/ → "Register a bot"
+# Or use Azure Portal: Azure Active Directory → App registrations → New registration
+# Then add the bot to Teams via the Bot Framework or App Studio.
+#
+# TEAMS_CLIENT_ID=                     # Azure AD App (client) ID
+# TEAMS_CLIENT_SECRET=                 # Azure AD client secret value
+# TEAMS_TENANT_ID=                     # Azure AD tenant ID (or "common" for multi-tenant)
+# TEAMS_ALLOWED_USERS=                 # Comma-separated AAD object IDs or UPNs
+# TEAMS_ALLOW_ALL_USERS=false          # Set true to skip the allowlist
+# TEAMS_HOME_CHANNEL=                  # Default channel/chat ID for cron delivery
+# TEAMS_HOME_CHANNEL_NAME=             # Display name for the home channel
+# TEAMS_PORT=3978                      # Webhook listen port (Bot Framework default)
+
+# =============================================================================
+# GOOGLE CHAT INTEGRATION
+# =============================================================================
+# Connects via Cloud Pub/Sub pull subscription (no public URL required).
+# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.
+# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.
+# 2. Create a Service Account with roles/pubsub.subscriber on the
+#    subscription (NOT project-wide); download the JSON key.
+# 3. Configure your Chat app at console.cloud.google.com/apis/credentials
+#    → Google Chat API → Configuration → Cloud Pub/Sub topic.
+# 4. (Optional, for native attachment delivery) Each user runs
+#    `/setup-files` once in their own DM after Pub/Sub is wired up.
+#
+# GOOGLE_CHAT_PROJECT_ID=                       # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)
+# GOOGLE_CHAT_SUBSCRIPTION_NAME=                # Full path: projects/<id>/subscriptions/<name>
+# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=             # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)
+# GOOGLE_CHAT_ALLOWED_USERS=                    # Comma-separated emails allowed to talk to the bot
+# GOOGLE_CHAT_ALLOW_ALL_USERS=false             # Set true to skip the allowlist
+# GOOGLE_CHAT_HOME_CHANNEL=                     # Default space (spaces/XXXX) for cron delivery
+# GOOGLE_CHAT_HOME_CHANNEL_NAME=                # Display name for the home channel
+
+# =============================================================================
+# A2A INTEGRATION
+# =============================================================================
+
+# A2A_AGENT_NAME=
+# A2A_HOST=
+# A2A_BEARER_TOKEN=
+
+# =============================================================================
+# A2A INTEGRATION
+# =============================================================================
+
+# API_SERVER_HOST=
+# API_SERVER_ENABLED=
+# API_SERVER_KEY=
+
+# =============================================================================
+# BUZZ INTEGRATION
+# =============================================================================
+
+# BUZZ_RELAY_URL=
+# BUZZ_PRIVATE_KEY=
+# BUZZ_HOME_CHANNEL_THREAD_ID=
+# BUZZ_ALLOWED_USERS=123123123,1231231234
+# BUZZ_DISPLAY_NAME=
+# BUZZ_TRANSPORT=
+
+# =============================================================================
+# DISCORD INTEGRATION
+# =============================================================================
+
+# DISCORD_BOT_TOKEN=
+# DISCORD_GUILD_ID=
+# DISCORD_CHANNEL_ID=

.gitattributes

@@ -1,3 +1,7 @@
+# Force LF line endings for shell/Python scripts
+*.sh text eol=lf
+*.py text eol=lf
+
 *.7z filter=lfs diff=lfs merge=lfs -text
 *.arrow filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
@@ -33,3 +37,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,15 @@
+# Environment and secrets
+.env
+.env.local
+*.pem
+
+# Dependencies and build
+node_modules/
+__pycache__/
+*.pyc
+
+# Logs and temp
+*.log
+.DS_Store
+
+graphify-out/

Dockerfile

@@ -0,0 +1,113 @@
+# ── Stage 1: Build Hermes Agent from source ──────────────────────────────
+FROM ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie AS uv_source
+FROM tianon/gosu:1.19-trixie AS gosu_source
+
+FROM debian:13.4
+SHELL ["/bin/bash", "-c"]
+
+ENV PYTHONUNBUFFERED=1
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright
+
+# ── System dependencies ──────────────────────────────────────────────────
+RUN echo "[build] Installing system deps..." && START=$(date +%s) \
+  && apt-get update && apt-get install -y --no-install-recommends \
+    build-essential python3 python3-pip python3-venv \
+    git curl wget ca-certificates \
+    ripgrep ffmpeg gcc python3-dev libffi-dev procps gnupg \
+    git git-lfs \
+    vim nano htop bash \
+    tar gzip xz-utils bzip2 rsync \
+    gettext-base openssh-client nginx \
+  && rm -rf /var/lib/apt/lists/* \
+  && pip3 install --no-cache-dir --break-system-packages huggingface_hub requests pyyaml \
+  && echo "[build] System deps: $(($(date +%s) - START))s"
+
+# Install Node.js 22 LTS (official binary). Debian 13's apt `nodejs` is v20.x with
+# npm 9.2.0, which fails Hermes' `npm install` (EBADENGINE): @electron/rebuild@4.2.0
+# requires node >=22.12.0 and react-router@8.3.0 requires node >=22.22.0 — the repo
+# sets engine-strict=true, so we pin the latest 22.x (22.23.2) that satisfies both.
+# The binary tarball is distro-agnostic and ships its own npm, avoiding apt lag.
+RUN echo "[build] Installing Node.js 22 LTS..." && START=$(date +%s) \
+  && curl -fsSL https://nodejs.org/dist/v22.23.2/node-v22.23.2-linux-x64.tar.xz -o /tmp/node.tar.xz \
+  && tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 \
+  && rm -f /tmp/node.tar.xz \
+  && node --version && npm --version \
+  && echo "[build] Node.js install: $(($(date +%s) - START))s"
+
+# ── Install buzz CLI (Rust, build only the buzz-cli crate) ────────────────
+# Provides the `buzz` binary needed by BUZZ_PRIVATE_KEY agent config.
+RUN echo "[build] Installing Rust + building buzz-cli..." && START=$(date +%s) \
+  && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable --profile minimal \
+  && . "$HOME/.cargo/env" \
+  && git clone --depth 1 https://github.com/block/buzz.git /tmp/buzz-src \
+  && cd /tmp/buzz-src \
+  && cargo build --release -p buzz-cli \
+  && cp target/release/buzz /usr/local/bin/buzz \
+  && chmod +x /usr/local/bin/buzz \
+  && cd / && rm -rf /tmp/buzz-src \
+  && echo "[build] buzz-cli: $(buzz --version 2>/dev/null || echo installed)" \
+  && echo "[build] Rust+buzz build: $(($(date +%s) - START))s"
+
+# ── Non-root user (uid 1000 — required for HF Spaces Dev Mode) ───────────
+RUN useradd -u 1000 -m -d /opt/data hermes
+
+COPY --chmod=0755 --from=gosu_source /gosu /usr/local/bin/
+COPY --chmod=0755 --from=uv_source /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/
+
+# ── Clone and build Hermes Agent ─────────────────────────────────────────
+RUN echo "[build] Cloning Hermes Agent..." && START=$(date +%s) \
+  && git clone --depth 1 https://github.com/NousResearch/hermes-agent.git /opt/hermes \
+  && echo "[build] Clone: $(($(date +%s) - START))s"
+
+WORKDIR /opt/hermes
+
+# ── Node dependencies + Playwright + Web Dashboard build ─────────────────
+RUN echo "[build] Installing Node deps + Playwright..." && START=$(date +%s) \
+  && npm install --prefer-offline --no-audit \
+  && npx playwright install --with-deps chromium --only-shell \
+  && if [ -d /opt/hermes/scripts/whatsapp-bridge ]; then \
+       cd /opt/hermes/scripts/whatsapp-bridge && npm install --prefer-offline --no-audit && npm install https-proxy-agent; \
+     fi \
+  && echo "[build] Building web dashboard..." \
+  && cd /opt/hermes/web && npm install --prefer-offline --no-audit && npm run build \
+  && cd /opt/hermes && npm cache clean --force \
+  && echo "[build] Node deps + web dashboard: $(($(date +%s) - START))s"
+
+# ── Python dependencies ──────────────────────────────────────────────────
+RUN chown -R hermes:hermes /opt/hermes
+USER hermes
+
+RUN echo "[build] Installing Python deps..." && START=$(date +%s) \
+  && cd /opt/hermes \
+  && UV_CACHE_DIR=/tmp/uv-cache uv venv \
+  && UV_CACHE_DIR=/tmp/uv-cache uv pip install --no-cache-dir -e ".[all]" \
+  && UV_CACHE_DIR=/tmp/uv-cache uv pip install --no-cache-dir huggingface_hub requests pyyaml \
+  && rm -rf /tmp/uv-cache \
+  && echo "[build] Python deps: $(($(date +%s) - START))s"
+
+USER root
+RUN chmod +x /opt/hermes/docker/entrypoint.sh
+
+# ── Prepare runtime dirs ─────────────────────────────────���──────────────
+RUN mkdir -p /opt/data/cron /opt/data/sessions /opt/data/logs /opt/data/hooks \
+             /opt/data/memories /opt/data/skills /opt/data/skins /opt/data/plans \
+             /opt/data/workspace /opt/data/home \
+  && chown -R 1000:1000 /opt/data
+
+USER root
+
+ARG CACHE_BUST=2026-07-18-wa-proxy-patch-v3
+RUN echo "Build: ${CACHE_BUST}"
+COPY --chown=root:root entrypoint.sh /opt/scripts/entrypoint.sh
+RUN chmod +x /opt/scripts/entrypoint.sh
+
+ENV HERMES_HOME=/opt/data
+ENV PATH="/opt/hermes/.venv/bin:$PATH"
+
+WORKDIR /app
+COPY --link ./ /app
+
+COPY nginx-proxy.conf /etc/nginx/proxy.conf
+COPY nginx.conf /etc/nginx/nginx.conf
+
+CMD ["/opt/scripts/entrypoint.sh"]

docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  hermes:
+    build: .
+    container_name: hermes
+    ports:
+      - "7860:7860"
+    env_file:
+      - .env
+    environment:
+      - HERMES_DASHBOARD_PASSWORD=${HERMES_DASHBOARD_PASSWORD:-}
+      - HERMES_DASHBOARD_USERNAME=${HERMES_DASHBOARD_USERNAME:-admin}
+    volumes:
+      - hermes_data:/data/hermes
+
+volumes:
+  hermes_data:

entrypoint.sh

@@ -0,0 +1,234 @@
+#!/bin/bash
+set -e
+
+BOOT_START=$(date +%s)
+
+echo "[entrypoint] Hermes Agent on HuggingFace Spaces (Safe Sync Mode)"
+echo "==============================================================================="
+
+# ── Configuration ───────────────────────────────────────────────────────────
+HERMES_WORK="/opt/data"                # Fast local filesystem (working dir)
+HERMES_BACKUP="/data/hermes"           # HF mounted bucket (backup only)
+INSTALL_DIR="/opt/hermes"
+HERMES_UID=1000
+HERMES_GID=1000
+SYNC_INTERVAL="${SYNC_INTERVAL:-60}"   # Default: sync every 1 minute
+
+# ── Singleton guard ──────────────────────────────────────────────────────────
+# Hanya satu instance yang menjalankan steps. Instance duplikat (dari HF rapid-
+# restart) cukup sleep infinity — tidak exit (exit = HF restart lagi).
+# HERMES_ENTRYPOINT_OWNER di-export sebelum exec gosu sehingga instance setelah
+# privilege-drop tahu dia adalah kelanjutan sah, bukan duplikat.
+ENTRYPOINT_PID_FILE="/tmp/hermes-entrypoint.pid"
+ENTRYPOINT_LOG="/tmp/hermes-entrypoint.log"
+
+if [ -z "${HERMES_ENTRYPOINT_OWNER:-}" ]; then
+  # Instance baru tanpa token → cek apakah ada instance lain yang sudah running
+  if [ -f "$ENTRYPOINT_PID_FILE" ]; then
+    OLD_PID=$(cat "$ENTRYPOINT_PID_FILE" 2>/dev/null || echo "")
+    if [ -n "$OLD_PID" ] && kill -0 "$OLD_PID" 2>/dev/null; then
+      echo "[entrypoint] Instance $OLD_PID already running — standing by silently."
+      sleep infinity
+      exit 0
+    else
+      echo "[entrypoint] Stale PID $OLD_PID (dead) — taking over..."
+      rm -f "$ENTRYPOINT_PID_FILE" "$ENTRYPOINT_LOG" 2>/dev/null || true
+    fi
+  fi
+  echo $$ > "$ENTRYPOINT_PID_FILE"
+  export HERMES_ENTRYPOINT_OWNER=$$
+  # Buat log world-writable sekarang (sebagai root) agar hermes bisa write setelah gosu
+  touch "$ENTRYPOINT_LOG" && chmod 666 "$ENTRYPOINT_LOG"
+fi
+
+exec > >(tee -a "$ENTRYPOINT_LOG") 2>&1
+
+# ── Helper: Safe Sync (EXCLUDE large/temp files) ───────────────────────────
+safe_sync() {
+  local SRC="$1"
+  local DST="$2"
+  
+  if [ ! -d "$SRC" ]; then
+    echo "  Source $SRC does not exist, skipping sync"
+    return 0
+  fi
+  
+  mkdir -p "$DST"
+  
+  echo "  Syncing: $SRC -> $DST"
+  echo "  Excluding: node_modules, .cache, logs, *.tmp, *.lock, *.pid, .local/share/uv"
+
+  rsync -a --checksum --delete \
+    --exclude='.local/share/uv' \
+    --exclude='node_modules' \
+    --exclude='.cache' \
+    --exclude='.playwright' \
+    --exclude='logs' \
+    --exclude='*.log' \
+    --exclude='*.log.*' \
+    --exclude='*.tmp' \
+    --exclude='*.lock' \
+    --exclude='*.pid' \
+    --exclude='__pycache__' \
+    --exclude='state.db-wal' \
+    --exclude='state.db-shm' \
+    "$SRC/" "$DST/"
+
+  echo "  ✓ Sync completed"
+}
+
+# ── Stage 1: Restore from backup (as root, before privilege drop) ──────────
+if [ "$(id -u)" = "0" ]; then
+  echo ""
+  echo "=== 1. Restoring Hermes data from persistent storage ==="
+  
+  # Create working directory on fast local filesystem
+  mkdir -p "$HERMES_WORK"/{cron,sessions,logs,hooks,memories,skills,skins,plans,workspace,home}
+  mkdir -p "$HERMES_BACKUP"/{cron,sessions,logs,hooks,memories,skills,skins,plans,workspace,home}
+  
+  # Restore from backup if exists
+  if [ -d "$HERMES_BACKUP" ] && [ "$(ls -A $HERMES_BACKUP 2>/dev/null | wc -l)" -gt 0 ]; then
+    echo "Found existing data in $HERMES_BACKUP"
+    RESTORE_START=$(date +%s)
+    safe_sync "$HERMES_BACKUP" "$HERMES_WORK"
+    RESTORE_END=$(date +%s)
+    echo "[TIMER] Restore from backup: $((RESTORE_END - RESTORE_START))s"
+    echo "Restore completed (sessions, memories, workspace restored)"
+  else
+    echo "No existing backup found, starting fresh"
+  fi
+  
+  # Fix ownership on working directory (fast - only local files)
+  chown -R ${HERMES_UID}:${HERMES_GID} "$HERMES_WORK"
+  echo "✓ Working directory ready: $HERMES_WORK (owned by hermes)"
+  
+  # Ensure /tmp is world-writable
+  chmod 1777 /tmp 2>/dev/null || true
+  
+  echo ""
+  echo "=== 2. Starting Scheduled Backup (Every ${SYNC_INTERVAL}s) ==="
+  # Background backup loop — uses safe_sync which already excludes .local/share/uv
+  (while true; do
+    sleep ${SYNC_INTERVAL}
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] Backing up $HERMES_WORK -> $HERMES_BACKUP"
+    safe_sync "$HERMES_WORK" "$HERMES_BACKUP"
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] Backup completed"
+  done) &
+  BACKUP_PID=$!
+  echo "Backup loop started with PID $BACKUP_PID"
+  
+  echo ""
+  echo "=== 3. Starting nginx reverse proxy (port 7860 → 7861) ==="
+  nginx
+  echo "  ✓ nginx started (PID $(cat /run/nginx.pid 2>/dev/null || echo unknown))"
+
+  echo ""
+  echo "=== 4. Dropping privileges to hermes (uid ${HERMES_UID}) ==="
+  exec gosu ${HERMES_UID} "$0" "$@"
+fi
+
+# ── Stage 2: Run as hermes user ─────────────────────────────────────────────
+echo ""
+echo "=== 4. Activating Python virtual environment ==="
+if [ -f "${INSTALL_DIR}/.venv/bin/activate" ]; then
+  source "${INSTALL_DIR}/.venv/bin/activate"
+  echo "✓ Activated venv: $(which python3)"
+fi
+
+# ── Bootstrap config files (in working dir, not mounted bucket) ─────────────
+echo ""
+echo "=== 5. Bootstrapping configuration files ==="
+
+if [ ! -f "$HERMES_WORK/.env" ] && [ -f "$INSTALL_DIR/.env.example" ]; then
+  cp "$INSTALL_DIR/.env.example" "$HERMES_WORK/.env"
+  echo "✓ Created .env from example"
+fi
+
+if [ ! -f "$HERMES_WORK/config.yaml" ] && [ -f "$INSTALL_DIR/cli-config.yaml.example" ]; then
+  cp "$INSTALL_DIR/cli-config.yaml.example" "$HERMES_WORK/config.yaml"
+  echo "✓ Created config.yaml from example"
+fi
+
+if [ ! -f "$HERMES_WORK/SOUL.md" ] && [ -f "$INSTALL_DIR/docker/SOUL.md" ]; then
+  cp "$INSTALL_DIR/docker/SOUL.md" "$HERMES_WORK/SOUL.md"
+  echo "✓ Created SOUL.md from template"
+fi
+
+# ── Dashboard basic auth ────────────────────────────────────────────────────
+DASH_USER="${HERMES_DASHBOARD_USERNAME:-admin}"
+DASH_PASS="${HERMES_DASHBOARD_PASSWORD:-}"
+if [ -n "$DASH_PASS" ] && [ -f "$HERMES_WORK/config.yaml" ]; then
+  if ! grep -q 'basic_auth' "$HERMES_WORK/config.yaml"; then
+    cat >> "$HERMES_WORK/config.yaml" <<EOF
+
+dashboard:
+  basic_auth:
+    username: ${DASH_USER}
+    password: ${DASH_PASS}
+EOF
+    echo "✓ Injected dashboard.basic_auth into config.yaml"
+  fi
+fi
+
+if [ -n "$DASH_PASS" ]; then
+  export HERMES_DASHBOARD_BASIC_AUTH_USERNAME="$DASH_USER"
+  export HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="$DASH_PASS"
+fi
+
+# ── Sync bundled skills ─────────────────────────────────────────────────────
+if [ -d "$INSTALL_DIR/skills" ] && [ -f "$INSTALL_DIR/tools/skills_sync.py" ]; then
+  python3 "$INSTALL_DIR/tools/skills_sync.py" 2>&1 || echo "[entrypoint] Skills sync skipped"
+fi
+
+# ── Build artifacts check ───────────────────────────────────────────────────
+echo ""
+echo "=== 6. Build artifacts check ==="
+test -f "$INSTALL_DIR/run_agent.py" && echo "  ✓ run_agent.py" || echo "  ⚠ run_agent.py not found"
+test -f "$INSTALL_DIR/gateway/run.py" && echo "  ✓ gateway/run.py" || echo "  ⚠ gateway/run.py not found"
+test -d "$INSTALL_DIR/web" && echo "  ✓ web/ dashboard" || echo "  ⚠ web/ not found"
+command -v hermes >/dev/null 2>&1 && echo "  ✓ hermes CLI: $(which hermes)" || echo "  ⚠ hermes CLI not in PATH"
+
+# ── Register Buzz profile ───────────────────────────────────────────────────
+if [ -n "${BUZZ_RELAY_URL:-}" ] && [ -n "${BUZZ_PRIVATE_KEY:-}" ]; then
+  _BUZZ_NAME="${BUZZ_DISPLAY_NAME:-${AGENT_NAME:-$(hostname)}}"
+  echo ""
+  echo "=== 7. Setting Buzz profile name: ${_BUZZ_NAME} ==="
+  buzz users set-profile --name "${_BUZZ_NAME}" 2>&1 || \
+    echo "⚠ buzz users set-profile failed (non-fatal)"
+fi
+
+# ── Export working directory as HERMES_HOME ─────────────────────────────────
+export HERMES_HOME="$HERMES_WORK"
+echo ""
+echo "=== 8. Environment Setup ==="
+echo "  Working directory (FAST): $HERMES_WORK"
+echo "  Backup directory (HF Bucket): $HERMES_BACKUP"
+echo "  Sync interval: ${SYNC_INTERVAL}s"
+echo "  HERMES_HOME: $HERMES_HOME"
+
+ENTRYPOINT_END=$(date +%s)
+echo ""
+echo "[TIMER] Entrypoint setup: $((ENTRYPOINT_END - BOOT_START))s"
+
+# ── Start Hermes Gateway ────────────────────────────────────────────────────
+echo ""
+echo "=== 9. Starting Hermes Agent ==="
+echo "  Hermes running on local filesystem: $HERMES_WORK (FAST)"
+echo "  Persistent storage: $HERMES_BACKUP (synced every ${SYNC_INTERVAL}s)"
+echo ""
+
+cd "$HERMES_WORK"
+
+# Trap SIGTERM untuk final backup sebelum shutdown (dipasang di Stage 2 karena exec gosu menggantikan Stage 1)
+trap "echo ''; echo 'Shutting down... performing final backup'; safe_sync '$HERMES_WORK' '$HERMES_BACKUP'; echo 'Final backup completed'; exit 0" SIGTERM SIGINT
+
+# # Initial backup segera setelah start (jangan tunggu interval pertama)
+# (sleep 30 && echo "[$(date '+%Y-%m-%d %H:%M:%S')] Initial post-start backup" && safe_sync "$HERMES_WORK" "$HERMES_BACKUP" && echo "[$(date '+%Y-%m-%d %H:%M:%S')] Initial backup done") &
+
+# Start dashboard di background (port 7861 untuk HF Spaces)
+"${INSTALL_DIR}/.venv/bin/hermes" dashboard --host 0.0.0.0 --port 7861 --no-open --insecure &
+DASHBOARD_PID=$!
+echo "  Dashboard started (PID $DASHBOARD_PID) on :7860"
+sleep 2
+
+exec "${INSTALL_DIR}/.venv/bin/python3" -u "${INSTALL_DIR}/gateway/run.py"

nginx-proxy.conf

@@ -0,0 +1,10 @@
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Port $server_port;
+proxy_set_header X-Forwarded-Host $host/a2a;
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+proxy_redirect off;
+proxy_read_timeout 300s;
+proxy_connect_timeout 10s;

nginx.conf

@@ -0,0 +1,33 @@
+worker_processes auto;
+events { worker_connections 1024; }
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+    sendfile on;
+
+    server {
+        listen 7860;
+        server_name _;
+
+        location / {
+            proxy_pass http://127.0.0.1:7861;
+            include /etc/nginx/proxy.conf;
+        }
+
+        location /8642/ {
+            proxy_pass http://127.0.0.1:8642/;
+            include /etc/nginx/proxy.conf;
+        }
+        
+        location /.well-known/agent-card.json {
+            proxy_pass http://127.0.0.1:9900/.well-known/agent-card.json;
+            include /etc/nginx/proxy.conf;
+        }
+
+        location /a2a/ {
+            proxy_pass http://127.0.0.1:9900/;
+            include /etc/nginx/proxy.conf;
+        }
+    }
+}

requirements.txt

@@ -0,0 +1 @@
+huggingface_hub>=0.24.5