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:

```text
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.