docs/ENVIRONMENT_CONFIGURATION.md

Environment Configuration

Configure secrets in Hugging Face Space Settings or inject them at container runtime. Never commit a populated .env file.

Core persistence

Variable	Default	Purpose
HF_TOKEN	none	Hugging Face token with required repository access.
HERMES_DATASET_REPO	derived/none	Private Dataset used to persist /opt/data.
AUTO_CREATE_DATASET	true	Create the private Dataset when missing.
SYNC_INTERVAL	60	Persistence sync interval in seconds.
HF_HUB_DOWNLOAD_TIMEOUT	implementation default	Hub download timeout.
HF_HUB_UPLOAD_TIMEOUT	implementation default	Hub upload timeout.
HERMES_HOME	/opt/data	Persistent Hermes data root.
MAX_BACKUPS	script default	Backup retention used by persistence helper.

Dashboard authentication

Variable	Default	Purpose
HERMES_ADMIN_PASSWORD	none	Required production dashboard password.
HERMES_ADMIN_USERNAME	admin	Username written to Hermes dashboard config by entrypoint.
HERMES_DASHBOARD_BASIC_AUTH_USERNAME	admin	Username checked by Futures router and runtime audit.
HERMES_DASHBOARD_BASIC_AUTH_SECRET	generated/persisted	Stable signing secret for password-login session cookies; set as a Space secret so restarts do not invalidate every browser session.
HERMES_GATEWAY_ENABLED	false	Opt-in Hermes messaging/cron worker; keep disabled for a stable dashboard-only Space.

For the audit tool only:

Variable	Purpose
HERMES_DASHBOARD_COOKIE	Existing authenticated session cookie when Basic auth is not used.
HERMES_FUTURES_BASE_URL	Default audit target base URL.

For a private Hugging Face Space, also provide HF_TOKEN to the audit process. The utility uses that bearer token only at the Hugging Face proxy, then uses HERMES_ADMIN_PASSWORD to establish the separate dashboard session cookie. Neither credential is written to the audit report.

Datasources

Variable	Default	Purpose
DS4_BASE_URL	DS4 Hugging Face Space URL	Authoritative Datasource 4 base.
DS4_TIMEOUT_S	6	DS4 request timeout.
DS2_BASE_URL	DS2 Hugging Face Space URL	Complementary Datasource 2 base.
DS2_TIMEOUT_S	6	DS2 request timeout.
HERMES_SYMBOL_CACHE_PATH	/opt/data/futures_symbols_cache.json	Symbol catalog cache.

Binance fallback

Variable	Default	Purpose
BINANCE_PUBLIC_FALLBACK_ENABLED	true	Enable unauthenticated field fallback.
BINANCE_FUTURES_PUBLIC_BASE_URL	https://fapi.binance.com	Binance Futures public base.
BINANCE_FUTURES_TIMEOUT_S	5	Request timeout.
BINANCE_FUTURES_MAX_RETRIES	2	Retry bound.
BINANCE_KLINE_INTERVAL	5m	Default fallback interval.
BINANCE_KLINE_LIMIT	100	Default kline count.
BINANCE_ATR_PERIOD	14	ATR lookback in fallback client.
BINANCE_ORDERBOOK_LIMIT	20	Depth level limit.
BINANCE_OI_PERIOD	5m	Open Interest history period.

A regional HTTP 451 must be surfaced honestly. Do not use raw IP, DNS bypass, or TLS bypass.

KuCoin Futures fallback

KuCoin is tried after Binance for missing or unusable public Futures fields. The client is read-only and does not require private credentials.

Variable	Default	Purpose
KUCOIN_FUTURES_PUBLIC_FALLBACK_ENABLED	true	Enable unauthenticated KuCoin fallback.
KUCOIN_FUTURES_PUBLIC_BASE_URL	https://api-futures.kucoin.com	KuCoin Futures public base.
KUCOIN_FUTURES_TIMEOUT_S	5	Request timeout.
KUCOIN_FUTURES_MAX_RETRIES	1	Retry bound.
FRESHNESS_FUTURE_TOLERANCE_SECONDS	120	Bounded provider/local clock-skew allowance; larger future timestamps remain invalid.

KuCoin values are labelled kucoin_futures; they must not be relabelled as Binance or Datasource 4 data. KuCoin contract metadata may independently verify an otherwise-unverified active Futures contract, but it cannot override an explicit Datasource 4 safety block or noTradeGuard.

Deterministic analysis

Variable	Default	Purpose
FUTURES_MIN_SIGNAL_SCORE	0.55	Minimum absolute deterministic score.
FUTURES_MIN_SIGNAL_COMPONENTS	3	Minimum present scoring components.
FUTURES_MIN_DIRECTION_CONFIRMATIONS	2	Minimum components confirming direction.
FUTURES_STOP_ATR_MULTIPLIER	1.2	ATR stop-distance multiplier.
FUTURES_TAKE_PROFIT_RR	1.8	Target reward-to-risk.
FUTURES_MIN_STOP_BPS	20	Minimum stop distance in basis points.
FUTURES_PLAN_MAX_AGE_SECONDS	20	Plan expiry window.
FUTURES_DEFAULT_LEVERAGE	5	Requested leverage before caps/haircut.

Changing these variables changes deterministic behavior and requires explicit review, tests, and deployment evidence.

Execution and Paper account

Variable	Default	Purpose
PAPER_EQUITY_USDT	implementation default	Initial Paper account equity.
FUTURES_EXCHANGE_ID	implementation default	Exchange adapter ID.
FUTURES_API_KEY	none	Exchange credential boundary. Do not set for routine Paper-only development.
FUTURES_API_SECRET	none	Exchange secret.
FUTURES_API_PASSPHRASE	none	Optional exchange passphrase.

Do not introduce credentials into source, logs, diagnostics, screenshots, patches, or generated reports.

Optional AI context (Hermes auxiliary)

Variable	Default	Purpose
EXTERNAL_AI_ENABLED	true	Allow optional AI context when explicitly requested (include_external_context).
EXTERNAL_AI_TOTAL_TIMEOUT_SECONDS	15	Outer safety cap for the futures_advisory auxiliary call in advisory.py; also seeds auxiliary.futures_advisory.timeout on first persist.
EXTERNAL_AI_TIMEOUT_SECONDS	8	Legacy per-call timeout (kept for compatibility).
OPENROUTER_ANALYSIS_MODEL	openai/gpt-4o-mini	OpenRouter model written into Hermes fallback_providers and auxiliary.futures_advisory by sync_hf.py on first persist.
GOOGLE_ANALYSIS_MODEL	gemini-2.5-flash	Gemini fallback model for the same chains.
HF_ANALYSIS_MODEL	meta-llama/Llama-3.1-8B-Instruct	Hugging Face fallback model for the same chains.
HERMES_OPENROUTER_FALLBACK_MODEL	none	Optional override that takes precedence over OPENROUTER_ANALYSIS_MODEL for fallback_providers.
HERMES_GOOGLE_FALLBACK_MODEL	none	Optional override that takes precedence over GOOGLE_ANALYSIS_MODEL for fallback_providers.
HERMES_HF_FALLBACK_MODEL	none	Optional override that takes precedence over HF_ANALYSIS_MODEL for fallback_providers.

Advisory is implemented via Hermes agent.auxiliary_client.async_call_llm with auxiliary task futures_advisory (registered by plugins/futures_trading/). Parsed output follows external_ai/advisory_schema.py. Advisory output cannot change the deterministic plan, risk approval, or execution gates.

scripts/sync_hf.py persists fallback_providers and auxiliary.futures_advisory.fallback_chain into Hermes config.yaml on first boot (or when an obsolete chain such as openrouter/free is detected). After that, set HERMES_PRESERVE_FALLBACK_PROVIDERS=true so operator/Hermes-UI edits are not overwritten each boot.

Hermes-wide auxiliary provider fallback (OpenRouter → Google → main model) for built-in tasks (compression, title_generation, web_extract) may still be configured when HERMES_MANAGE_AUXILIARY_FALLBACKS=true.

Analysis model env vars are read by scripts/sync_hf.py when building the initial advisory chain. They are not read directly by external_ai/advisory.py, which routes through Hermes auxiliary task routing only.

Deprecated (ignored): EXTERNAL_AI_PROVIDER_ORDER, EXTERNAL_AI_PROVIDER_TIMEOUT_SECONDS — pre-migration direct-chain knobs with no runtime consumer.

Telegram webhook

Variable	Default	Purpose
TELEGRAM_ENABLED	false	Enable webhook adapter.
TELEGRAM_MODE	webhook	Must remain webhook mode.
TELEGRAM_PUBLIC_BASE_URL	Space URL	Webhook target base.
TELEGRAM_WEBHOOK_PATH	/api/telegram/webhook	Webhook path.
TELEGRAM_WEBHOOK_SECRET	none	Telegram secret-token header value.
TELEGRAM_BOOTSTRAP_SECRET	none	One-time owner claim secret.
TELEGRAM_ALLOWED_USER_IDS	empty	Comma-separated authorized IDs.
TELEGRAM_BOT_TOKEN	none	Telegram bot token.
TELEGRAM_PROXY_URL	empty	Optional direct Bot API proxy.
TELEGRAM_RELAY_URL	empty	Optional proactive relay.
TELEGRAM_RELAY_SECRET	empty	HMAC relay secret.
TELEGRAM_STATE_PATH	/opt/data/telegram_state.json	Persisted owner/watchlist state.
TELEGRAM_ALERTS_ENABLED	false	External-scheduler alert evaluation status.
TELEGRAM_COMMAND_RATE_LIMIT	10	Commands per user per minute.
TELEGRAM_SCAN_MAX_SYMBOLS	300	Maximum verified catalog candidates.
TELEGRAM_SCAN_SHORTLIST_SIZE	20	Deterministic shortlist size.
TELEGRAM_SCAN_RESULT_COUNT	10	Displayed result count.
TELEGRAM_SCAN_MAX_CONCURRENCY	4	Analysis concurrency.

MCP isolation

Variable	Default	Requirement
LINEAR_MCP_ENABLED	false	Keep unchanged unless separately approved.
UNREAL_ENGINE_MCP_ENABLED	false	Keep disabled unless separately approved.

Runtime integrity paths

Advanced overrides used by diagnostics:

HERMES_FUTURES_OVERLAY_MANIFEST
HERMES_OVERLAY_SOURCE
HERMES_SYNC_SCRIPT

These should normally use their runtime defaults.

Cold-start and provider fallback controls

Variable	Default	Purpose
DS4_TIMEOUT_S	6	Fast-path DS4 request timeout.
DS4_WAKE_TIMEOUT_S	25	One extended retry used only after a retryable DS4 cold-start failure.
HERMES_MAX_CONCURRENT_SESSIONS	1	Resource-safe active session cap written to config.yaml.
HERMES_MANAGE_AUXILIARY_FALLBACKS	true	Configure OpenRouter → Google → main-model fallback for Hermes text auxiliary tasks.
HERMES_PRESERVE_FALLBACK_PROVIDERS	true (Space)	Preserve operator/Hermes-UI fallback_providers and auxiliary.futures_advisory after initial persist; obsolete chains are still refreshed.

HTTP 402 is terminal only for the current advisory provider. It is not retried against the same provider and the next configured provider is attempted within the total advisory deadline.