.env.example

# ── Server ────────────────────────────────────────────────────────────────
PORT=3030
NODE_ENV=development
LOG_LEVEL=info

# ── Database (SQLite, file-based — no server to provision) ──────────────────
# Path is relative to the prisma/ directory (so this resolves to api/prisma/dev.db).
DATABASE_URL=file:./dev.db

# ── GitHub App ───────────────────────────────────────────────────────────────
# From the GitHub App settings page.
GITHUB_APP_ID=000000
# The webhook secret you configured on the App.
GITHUB_WEBHOOK_SECRET=replace-me
# The App private key (PEM). Either inline (with literal \n) or a file path via GITHUB_APP_PRIVATE_KEY_PATH.
GITHUB_APP_PRIVATE_KEY=
GITHUB_APP_PRIVATE_KEY_PATH=./github.pem

# ── Sandbox & Hermes runtime ─────────────────────────────────────────────────
# How and where the Hermes Agent CLI runs. Run `npm run hermes:docker` (repo root) to build
# the agent image and populate SANDBOX_MODE / DOCKER_AGENT_IMAGE / HERMES_HOME automatically.
#
# SANDBOX_MODE:
#   none    = run hermes as a local subprocess using the system Hermes binary. Set HERMES_HOME
#             to your existing Hermes data dir (e.g. ~/.hermes) — Hermes reads its own config.yaml
#             from there. HERMES_PRIMARY_MODEL / HERMES_PRIMARY_PROVIDER / HERMES_TIMEOUT_MS still
#             apply, passed as CLI flags at invocation time.
#   default = run hermes inside a Docker container (recommended; requires DOCKER_AGENT_IMAGE).
SANDBOX_MODE=default
DOCKER_AGENT_IMAGE=hermes-agent:latest
# Name/path of the hermes executable used in SANDBOX_MODE=none.
HERMES_BIN=hermes
# HERMES_HOME is the hermes data directory — config, memory notes (MEMORY.md/USER.md), skills, and
# sessions. api/.hermes/ ships a config.base.yaml template and SOUL.md; a config.yaml is generated
# from it at startup using the env-var values below. In SANDBOX_MODE=default, MEMORY.md, USER.md,
# skills/, and config.yaml are bind-mounted into each agent container so settings and learning
# persist across invocations.
HERMES_HOME=./.hermes

# ── Models & roles ───────────────────────────────────────────────────────────
# Each role is a model + provider pair. The provider name selects a credential from the
# "Provider API keys" section below. Model/provider are passed to Hermes as CLI flags.
# Primary — used for PLAN and IMPLEMENT/REVISE. Required in SANDBOX_MODE=default: the Docker
# container has no pre-existing Hermes config to fall back on, so these must be set or the agent
# fails with "No LLM provider configured". Optional in SANDBOX_MODE=none (Hermes reads config.yaml).
HERMES_PRIMARY_MODEL=
HERMES_PRIMARY_PROVIDER=
# Review — optional override for review steps. Lets a more capable or independent model review
# than the one used for implementation. Falls back to the primary model when unset.
#HERMES_REVIEW_MODEL=
#HERMES_REVIEW_PROVIDER=
# Auxiliary — optional override for Hermes' background tasks (context compression, vision analysis,
# web-extract). Point at a smaller/faster model so secondary work delegated by the main agent
# doesn't compete with it. Both optional and independent; if unset, Hermes uses its own auxiliary
# defaults ("auto" provider).
#HERMES_AUXILIARY_MODEL=
#HERMES_AUXILIARY_PROVIDER=
# Judge — optional override for the completion judge that decides, after each IMPLEMENT/REVISE pass,
# whether the plan's acceptance criteria are met (and continues the agent with a critique if not).
# Falls back to the review model, then the primary model. A weak model makes an unreliable judge —
# prefer a capable one.
#HERMES_JUDGE_MODEL=
#HERMES_JUDGE_PROVIDER=

# ── Provider API keys (cloud / remote inference) ─────────────────────────────
# Credentials are keyed by PROVIDER, not by role: each HERMES_*_PROVIDER above names a provider
# (e.g. openai, anthropic) and Hermes reads that provider's key from the matching standard env var
# below — and already knows its base URL, so no per-provider URL is needed. (The `custom` provider
# is the exception: its endpoint is HERMES_MODEL_BASE_URL; local Ollama needs no key at all.) Set
# only the keys for providers you actually use. Hermes reads these standard names directly from the
# environment (no translation). In SANDBOX_MODE=default they are forwarded by name into each agent
# container (the value never appears in the stored command line); in SANDBOX_MODE=none the Hermes
# subprocess inherits them directly. Recognised: OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
# XAI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY,
# DASHSCOPE_API_KEY (Qwen cloud), MINIMAX_API_KEY, KIMI_API_KEY, GLM_API_KEY/ZAI_API_KEY (z.ai),
# AZURE_FOUNDRY_API_KEY, OLLAMA_API_KEY, GMI_API_KEY. Nous Portal / Claude Max use OAuth credential
# files (ANTHROPIC_TOKEN / CLAUDE_CODE_OAUTH_TOKEN are forwarded as fallbacks).
#OPENAI_API_KEY=
#ANTHROPIC_API_KEY=
# API key for the `custom` provider (a local or self-hosted OpenAI-compatible inference server that
# requires auth — e.g. HERMES_PRIMARY_PROVIDER=custom with HERMES_MODEL_BASE_URL set). Hermes' custom
# provider authenticates via OPENAI_API_KEY; this is exposed to Hermes under that name at startup, so
# you get an unambiguous variable without overloading OPENAI_API_KEY. An explicitly set OPENAI_API_KEY
# takes precedence. Leave unset for keyless local servers (Ollama, vLLM, llama.cpp).
#CUSTOM_API_KEY=

# ── Inference tuning ─────────────────────────────────────────────────────────
# Hard wall-clock ceiling (ms) for a single Hermes invocation — the process is killed regardless
# of activity once this elapses. For local inference with large models, increase this; a full
# implementation cycle can take well over an hour on modest hardware.
HERMES_TIMEOUT_MS=7200000
# Maximum context window size (tokens) passed to Hermes as context_length in config.yaml. Must
# match the model's actual context window — too large causes OOM on the inference server; too small
# causes premature compression. Omit to let Hermes use its model default.
HERMES_CONTEXT_LENGTH=131072
# Fraction of the context window (0–1) at which Hermes compresses older messages to free space.
# Lower values compress more aggressively; higher values preserve more history at the cost of
# context pressure. Omit to use the Hermes default (0.5).
HERMES_COMPRESS_THRESHOLD=0.80
# OpenAI-compatible base URL for the model provider. Only needed for the `custom` provider
# (local/self-hosted endpoints) — named cloud providers already know their own URL. In
# SANDBOX_MODE=default this is automatically rewritten to host.docker.internal so the agent
# container can reach a local inference server running on the host. Omit to use the Hermes default
# (Ollama at http://localhost:11434/v1).
HERMES_MODEL_BASE_URL=http://localhost:11434/v1

# ── Browser (optional — Camofox) ────────────────────────────────────────────
# Camofox is a self-hosted Firefox-based stealth browser server. When set, all hermes browser tools
# route through Camofox instead of the cloud providers. Leave empty to disable (hermes falls back to
# agent-browser). Start Camofox: git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser && make up
# For SANDBOX_MODE=default the agent container automatically uses host.docker.internal; for
# SANDBOX_MODE=none set this to http://localhost:9377.
CAMOFOX_URL=

# ── Observability ────────────────────────────────────────────────────────────
# Diagnostic: when true, logs a compact identity line (type/name/model/usage/attribute keys) for
# every incoming trace span. Use to inspect exactly how Hermes traces compression and other
# auxiliary calls. Noisy — leave off in normal operation.
#LANGFUSE_DEBUG_SPANS=false

# ── Orchestration policy ─────────────────────────────────────────────────────
# Only issues with this label are picked up.
TRIGGER_LABEL=hermes
# Review confidence (0-100) required before opening a PR.
REVIEW_CONFIDENCE_THRESHOLD=85
MAX_PLAN_REVISIONS=10
# Max VERIFY→REVISE iterations per cycle before opening a draft PR with tests still red.
MAX_VERIFY_ATTEMPTS=3
# Max completion-judge continuations per IMPLEMENT/REVISE pass before proceeding to VERIFY
# anyway. Each continuation re-runs the agent with the judge's critique. 0 disables the loop.
MAX_COMPLETION_RETRIES=3
# Max review passes per cycle before opening a draft PR.
MAX_REVIEW_PASSES=3
# Max CONSECUTIVE review passes whose output can't be parsed into a verdict before giving up on
# self-review and opening a draft PR. Each unparseable pass is re-run with stricter schema guidance;
# only after this many in a row do we bail (a stray single failure among good passes never counts).
MAX_REVIEW_RETRIES=2
# Soft cap on lines returned to the IMPLEMENT/REVISE *primary* agent from a single file read.
# Beyond this the read is truncated with a note to delegate the survey to a sub-agent (sub-agents
# are uncapped) — stops the orchestrator bloating its own context by reading large files itself.
# Verification/quote-a-function reads stay well under it; only wholesale surveys get clipped.
PRIMARY_READ_MAX_LINES=300
# Slash-command prefix used in issue comments (e.g. "/hermes approve").
COMMAND_PREFIX=/hermes

# ── Queue / worker ───────────────────────────────────────────────────────────
WORKER_ENABLED=true
WORKER_CONCURRENCY=2
# How often the worker polls for due tasks (ms).
WORKER_POLL_INTERVAL_MS=2000
QUEUE_MAX_ATTEMPTS=3
# Backoff base (ms); delay = base * 2^(attempt-1).
QUEUE_BACKOFF_BASE_MS=15000
# A task RUNNING longer than this (ms) is considered orphaned and reclaimable.
QUEUE_LOCK_TTL_MS=3600000

# ── Workspace / git ──────────────────────────────────────────────────────────
# Path to the directory where per-job git worktrees are cloned. When running via docker-compose,
# this is overridden to ${PWD}/workspaces and mounted at that same absolute path inside the
# container so sibling agent containers (spawned via the Docker socket) can reference workspace
# directories by the same path the host sees.
WORKSPACE_ROOT=./.workspaces
GIT_AUTHOR_NAME=Hermes Agent
GIT_AUTHOR_EMAIL=hermes@users.noreply.github.com
# Branch name template; {issue} is replaced with the issue number.
BRANCH_PREFIX=hermes/issue-
# Optional dedicated SSH deploy key for cloning/pushing DASHBOARD-origin jobs (created from the UI)
# against an SSH remote. Leave UNSET to use the host's own SSH setup (ssh-agent, ~/.ssh/config,
# default keys) exactly as a normal `git clone git@…` would — this is the usual case when the
# orchestrator runs on a host that already has repo access. Set it only to force an isolated key
# (it then ignores the host agent via IdentitiesOnly). Powerful — it can push to any repo it's
# authorised for; mount it read-only and never expose it to the agent container (git runs on the
# orchestrator host, not the agent sandbox).
#GIT_SSH_KEY_PATH=/home/youruser/.ssh/olympian_deploy_key