Configuration

The hermes-bridge service is configured entirely through environment variables. Required values are validated on startup — a missing or malformed value fails fast with a descriptive error rather than starting in a broken state.

DonutChat side

Variable	Required	Default	Description
`DONUT_BOT_TOKEN`	✅	—	The bridged bot’s `donutbot_…` token.
`DONUT_STREAM_URL`	✅	—	Bot event WebSocket URL, e.g. `wss://api.donutchat.com/bots/v1/stream`.
`DONUT_SEND_URL`	✅	—	Bot send API URL, e.g. `https://api.donutchat.com/bots/v1/messages`.
`DONUT_TYPING_URL`	optional	(empty)	Typing-indicator URL, e.g. `https://api.donutchat.com/bots/v1/typing`. Empty disables the thinking indicator.
`BRIDGE_REPLY_CONTENT_TYPE`	optional	`MD`	Content type for posted replies — `MD` (markdown) or `TX` (plain text).

Hermes side

Variable	Required	Default	Description
`HERMES_BASE_URL`	✅	—	Base URL of the Hermes OpenAI-compatible API server, e.g. `http://hermes-host:8642`. Keep it private.
`HERMES_API_KEY`	✅	—	API key for the Hermes API server (`API_SERVER_KEY` on the Hermes box).
`HERMES_MODEL`	optional	`hermes`	Model name passed to `/v1/chat/completions`.
`BRIDGE_SYSTEM_PROMPT`	optional	(empty)	System prompt prepended to each conversation.

Behavior

Variable	Required	Default	Description
`BRIDGE_MAX_CONCURRENT`	optional	`4`	Max parallel Hermes calls across chats. Must be ≥ 1. Within a single chat, messages are always serialized.
`BRIDGE_REQUEST_TIMEOUT`	optional	`120s`	Per-call timeout for a Hermes request. Go duration syntax (e.g. `90s`, `2m`). Must be positive.
`BRIDGE_RESPOND_TO_BOTS`	optional	`false`	When `false`, the bridge ignores messages from other bots/webhooks/feeds — a loop guard. Set `true` only if you intentionally want bot-to-bot replies.

Failure handling

Variable	Required	Default	Description
`BRIDGE_BREAKER_THRESHOLD`	optional	`3`	Consecutive Hermes failures that open the circuit breaker. Must be ≥ 1.
`BRIDGE_BREAKER_COOLDOWN`	optional	`60s`	How long the breaker stays open before admitting one probe. Go duration syntax. Must be positive.
`BRIDGE_FALLBACK_MESSAGE`	optional	`⚠️ The agent is unavailable right now. Please try again later.`	Posted to a chat (rate-limited) when the breaker is open. Must be non-empty and ≤ 4000 bytes.

Validation rules

On startup the bridge rejects:

Any missing required variable (DONUT_BOT_TOKEN, DONUT_STREAM_URL, DONUT_SEND_URL, HERMES_BASE_URL, HERMES_API_KEY).
BRIDGE_MAX_CONCURRENT or BRIDGE_BREAKER_THRESHOLD less than 1.
A non-positive BRIDGE_REQUEST_TIMEOUT or BRIDGE_BREAKER_COOLDOWN.
A malformed integer / boolean / duration for any typed variable.
An empty or over-4000-byte BRIDGE_FALLBACK_MESSAGE.

Terraform variables (ECS)

When deploying via infra/, these map onto the environment above:

Terraform variable	Maps to	Notes
`hermes_bridge_enabled`	(deploy toggle)	`false` by default; set `true` to create the service + secret.
`hermes_bridge_bot_token`	`DONUT_BOT_TOKEN`	Sensitive → Secrets Manager.
`hermes_bridge_api_key`	`HERMES_API_KEY`	Sensitive → Secrets Manager.
`hermes_bridge_stream_url`	`DONUT_STREAM_URL`	Plain env var.
`hermes_bridge_send_url`	`DONUT_SEND_URL`	Plain env var.
`hermes_bridge_typing_url`	`DONUT_TYPING_URL`	Plain env var.
`hermes_bridge_hermes_base_url`	`HERMES_BASE_URL`	Plain env var; use a private address.
`hermes_bridge_model`	`HERMES_MODEL`	Plain env var.