Environment Variables

Hayhooks can be configured via environment variables. Most app settings use the HAYHOOKS_ prefix (plus the legacy LOG alias for log level), while tracing uses standard OpenTelemetry OTEL_* variables. This page lists the canonical variables supported by the codebase.

Server

HAYHOOKS_HOST

• Default: localhost
• Description: Host for the FastAPI app

HAYHOOKS_PORT

• Default: 1416
• Description: Port for the FastAPI app

HAYHOOKS_ROOT_PATH

• Default: ""
• Description: Root path to mount the API under (FastAPI root_path)

HAYHOOKS_PIPELINES_DIR

• Default: ./pipelines
• Description: Directory containing pipelines to auto-deploy on startup. In durable mode it must exist, and it is the complete, fixed pipeline set

HAYHOOKS_ADDITIONAL_PYTHON_PATH

• Default: ""
• Description: Additional path appended to sys.path for wrapper imports

HAYHOOKS_USE_HTTPS

• Default: false
• Description: Use HTTPS when the CLI calls the server (affects CLI only)

HAYHOOKS_DISABLE_SSL

• Default: false
• Description: Disable SSL verification for CLI calls

HAYHOOKS_SHOW_TRACEBACKS

• Default: false
• Description: Include tracebacks in error messages (server and MCP)

HAYHOOKS_GRACEFUL_SHUTDOWN_TIMEOUT

• Default: 5
• Description: Seconds the server waits for open connections to finish on shutdown before cancelling them (0–300). In durable mode, open SSE streams hold this wait; see Durable Operations.

HAYHOOKS_STREAMING_COMPONENTS

• Default: "" (empty string)
• Description: Global configuration for which pipeline components should stream
• Options:
• "" (empty): Stream only the last capable component (default)
• "all": Stream all streaming-capable components
• Comma-separated list: "llm_1,llm_2" to enable specific components

Priority Order

Pipeline-specific settings (via streaming_components parameter or YAML) override this global default.

Component-Specific Control

For component-specific control, use the streaming_components parameter in your code or YAML configuration instead of the environment variable to specify exactly which components should stream.

Examples:

# Stream all components globally
export HAYHOOKS_STREAMING_COMPONENTS="all"

# Stream specific components (comma-separated, spaces are trimmed)
export HAYHOOKS_STREAMING_COMPONENTS="llm_1,llm_2"
export HAYHOOKS_STREAMING_COMPONENTS="llm_1, llm_2, llm_3"

Deploy Performance

These settings apply to live deployment. Durable mode ignores them: it loads the pipelines sequentially at startup and has no deploy or undeploy operations.

HAYHOOKS_DEPLOY_CONCURRENCY

• Default: serialized
• Description: Controls how runtime deploy/undeploy operations (via HTTP API and MCP) are synchronized
• Options:
• "serialized" (default): One deploy/undeploy at a time. Safest option; prevents race conditions on the pipeline registry and FastAPI route table.
• "parallel": Allow concurrent deploy/undeploy operations. Higher throughput for admin traffic, but carries a higher risk of race conditions.

HAYHOOKS_STARTUP_DEPLOY_STRATEGY

• Default: parallel
• Description: Controls how pipelines are deployed from HAYHOOKS_PIPELINES_DIR at startup
• Options:
• "sequential": Deploy one pipeline at a time (original behavior).
• "parallel" (default): Prepare pipelines in a bounded thread pool, then commit routes serially and rebuild the OpenAPI schema once at the end. Significantly faster when many pipelines are deployed.

HAYHOOKS_STARTUP_DEPLOY_WORKERS

• Default: 4
• Description: Maximum number of worker threads used for parallel startup deployment (only effective when HAYHOOKS_STARTUP_DEPLOY_STRATEGY=parallel)

Examples:

# Fastest startup: parallel with 8 workers
export HAYHOOKS_STARTUP_DEPLOY_STRATEGY=parallel
export HAYHOOKS_STARTUP_DEPLOY_WORKERS=8

# Safe runtime: serialize all deploy/undeploy (default)
export HAYHOOKS_DEPLOY_CONCURRENCY=serialized

# Allow concurrent runtime deploys (advanced)
export HAYHOOKS_DEPLOY_CONCURRENCY=parallel

Terminal Monitoring

HAYHOOKS_MONITORING_ENABLED

• Default: true
• Description: Index new durable submissions and enable authenticated execution collection routes on every writing replica. Disable with hayhooks run --without-monitoring. Does not launch a TUI. Existing executions are not backfilled; collections require owner or operator authentication.

HAYHOOKS_DASHBOARD_TOKEN

• Default: unset
• Description: Terminal client bearer token. Sent as Authorization: Bearer .... When unset, local POSIX clients discover the private same-user dashboard credential for literal loopback URLs only.

HAYHOOKS_DASHBOARD_API_KEY

• Default: unset
• Description: Terminal client API key. Sent in X-API-Key by default.

HAYHOOKS_DASHBOARD_API_KEY_HEADER

• Default: X-API-Key
• Description: HTTP header name for the terminal client's API key.

These credential variables configure only the terminal client, not server authentication. The client always verifies TLS. Configure REQUESTS_CA_BUNDLE when the server uses a private certificate authority.

Durable Mode

HAYHOOKS_DURABLE_MODE

• Default: false
• Description: Fix the pipeline set at startup and host durable wrappers. Pipelines load once from HAYHOOKS_PIPELINES_DIR; deploy and undeploy are disabled, so changing a pipeline means restarting the server. See Durable mode.

HAYHOOKS_DURABLE_RELEASE_RUNNING_ON_SHUTDOWN

• Default: false
• Description: At the end of the shutdown grace, hand the claims of work that is still running to another process instead of waiting for it. See Hosts with short kill deadlines.

The remaining durable settings apply only in durable mode, and only when at least one durable wrapper is loaded. Redis is the production default; set HAYHOOKS_DURABLE_STORE=memory only for local development or tests.

Variable	Default	Purpose
HAYHOOKS_DURABLE_STORE	redis	redis or process-local memory storage
HAYHOOKS_DURABLE_REDIS_URL	redis://localhost:6379/0	Worker and viewer Redis URL; query options override both clients' defaults
HAYHOOKS_DURABLE_REDIS_KEY_PREFIX	hayhooks:durable	Private Redis key namespace
HAYHOOKS_DURABLE_REDIS_MAX_VIEWERS	100	Viewer connection pool: concurrent blocked durable SSE reads per process; an extra stream waits up to 1 s for a connection
HAYHOOKS_DURABLE_TERMINAL_TTL_SECONDS	604800	Terminal record and idempotency retention
HAYHOOKS_DURABLE_MAX_NONTERMINAL_EXECUTIONS	1000	Admission ceiling per deployment; 0 opts into unlimited admission
HAYHOOKS_DURABLE_MAX_PAYLOAD_BYTES	1000000	Maximum encoded input/checkpoint/result/error/wait payload
HAYHOOKS_DURABLE_MAX_PROGRESS_EVENTS	100	Buffered and retained progress events per execution
HAYHOOKS_DURABLE_MAX_PROGRESS_EVENT_BYTES	8192	Maximum encoded progress event
HAYHOOKS_DURABLE_MAX_STREAM_CHUNKS	100	Retained SSE display chunks; 0 disables chunks
HAYHOOKS_DURABLE_MAX_STREAM_CHUNK_BYTES	64000	Maximum encoded display chunk
HAYHOOKS_DURABLE_WORKER_CONCURRENCY	1	Worker slots per durable deployment and process
HAYHOOKS_DURABLE_POLL_INTERVAL_SECONDS	5.0	Maximum pickup delay for work submitted on another replica; local submissions wake idle workers immediately
HAYHOOKS_DURABLE_MAINTENANCE_INTERVAL_SECONDS	5.0	Maximum additional expired-lease recovery delay
HAYHOOKS_DURABLE_SHUTDOWN_GRACE_SECONDS	5.0	Grace before cancelling workers on shutdown; not a bound on shutdown time
HAYHOOKS_DURABLE_LEASE_DURATION_MS	30000	Fenced claim lease duration
HAYHOOKS_DURABLE_LEASE_COMMIT_SAFETY_MS	1500	Minimum lease time remaining for owned commits
HAYHOOKS_DURABLE_MAX_RUN_ATTEMPTS	3	Lost leases (crash or stall) after which an execution fails; handoffs, resumes, and application retries don't count
HAYHOOKS_DURABLE_MAX_APPLICATION_RETRIES	2	Retries explicitly requested by application code
HAYHOOKS_DURABLE_RETRY_BASE_DELAY_SECONDS	1.0	Default exponential retry base delay
HAYHOOKS_DURABLE_RETRY_MAX_DELAY_SECONDS	60.0	Default retry delay ceiling

For HAYHOOKS_DURABLE_REDIS_URL, a socket_timeout must exceed the 15-second SSE block or startup fails. Do not set max_connections, timeout, protocol, retry_on_timeout, or legacy_responses in the URL. Use HAYHOOKS_DURABLE_REDIS_MAX_VIEWERS to bound viewer connections.

See Durable Operations before changing polling, leases, retention, capacity, or Redis persistence. Worker polling and lease maintenance are independent: lowering one does not make the other run more frequently.

MCP

HAYHOOKS_MCP_HOST

• Default: localhost
• Description: Host for the MCP server

HAYHOOKS_MCP_PORT

• Default: 1417
• Description: Port for the MCP server

A2A

HAYHOOKS_A2A_HOST

• Default: localhost
• Description: Host for the A2A server

HAYHOOKS_A2A_PORT

• Default: 1418
• Description: Port for the A2A server

HAYHOOKS_A2A_EXTERNAL_URL

• Default: "" (empty)
• Description: Base URL advertised in A2A agent cards (e.g. when Hayhooks runs behind a reverse proxy). When empty, defaults to http://{HAYHOOKS_A2A_HOST}:{HAYHOOKS_A2A_PORT}

HAYHOOKS_A2A_V0_3_COMPAT

• Default: true
• Description: Accept A2A spec 0.3 requests on the same endpoints. Many clients and tools (e.g. the a2a-inspector) still speak 0.3 during the 1.0 transition

Chainlit UI

HAYHOOKS_CHAINLIT_ENABLED

• Default: false
• Description: Enable the embedded Chainlit chat UI

HAYHOOKS_CHAINLIT_PATH

• Default: /chat
• Description: URL path where the Chainlit UI is mounted

HAYHOOKS_CHAINLIT_APP

• Default: "" (uses built-in default app)
• Description: Path to a custom Chainlit app file

HAYHOOKS_CHAINLIT_DEFAULT_MODEL

• Default: "" (auto-selects if only one pipeline is deployed)
• Description: Default pipeline/model to auto-select in the Chainlit UI

HAYHOOKS_CHAINLIT_REQUEST_TIMEOUT

• Default: 120.0
• Description: Timeout in seconds for chat completion requests from the Chainlit UI

HAYHOOKS_CHAINLIT_CUSTOM_ELEMENTS_DIR

• Default: "" (no custom elements)
• Description: Path to a directory containing custom .jsx element files. These files are copied into the Chainlit public/elements/ directory at startup and become available as cl.CustomElement targets. See Custom Elements.

Installation Required

The Chainlit UI requires the chainlit extra: pip install "hayhooks[chainlit]"

Local tracing

Setting	Default	Purpose
HAYHOOKS_TRACING_ENABLED	true	Mount the authenticated local trace API
HAYHOOKS_TRACING_TOKEN	unset	Explicit operator bearer token; loopback POSIX servers otherwise use a private local credential
HAYHOOKS_TRACING_BUFFER_CAPACITY	200	Maximum retained process traces
HAYHOOKS_TRACING_DEFAULT_LIMIT	25	Default trace snapshot size
HAYHOOKS_TRACING_MAX_LIMIT	100	Maximum trace snapshot size (also capped at 100 and buffer capacity)
HAYHOOKS_TRACING_SLOW_COMPONENT_MS	1000	Minimum completed duration for slow-component highlighting
HAYHOOKS_TRACING_INCLUDE_HAYSTACK_SPANS	true	Mirror Haystack components into the local buffer
HAYHOOKS_TRACING_INCLUDE_PAYLOAD_VALUES	false	Include redacted raw request values in tags

The local API requires operator authorization. See terminal tracing for scope, authentication, payload precautions and migration from the removed browser dashboard.

CORS

These map 1:1 to FastAPI CORSMiddleware and the settings in hayhooks.settings.AppSettings.

HAYHOOKS_CORS_ALLOW_ORIGINS

• Default: ["*"]
• Description: List of allowed origins

HAYHOOKS_CORS_ALLOW_METHODS

• Default: ["*"]
• Description: List of allowed HTTP methods

HAYHOOKS_CORS_ALLOW_HEADERS

• Default: ["*"]
• Description: List of allowed headers

HAYHOOKS_CORS_ALLOW_CREDENTIALS

• Default: false
• Description: Allow credentials

HAYHOOKS_CORS_ALLOW_ORIGIN_REGEX

• Default: null
• Description: Regex pattern for allowed origins

HAYHOOKS_CORS_EXPOSE_HEADERS

• Default: []
• Description: Headers to expose in response

HAYHOOKS_CORS_MAX_AGE

• Default: 600
• Description: Maximum age for CORS preflight responses in seconds

Logging

HAYHOOKS_LOG_LEVEL

• Default: INFO
• Alias: LOG (legacy, lower priority)
• Description: Minimum log level to display (consumed by Loguru). When both HAYHOOKS_LOG_LEVEL and LOG are set, HAYHOOKS_LOG_LEVEL takes precedence.

HAYHOOKS_LOG_FORMAT

• Default: default
• Description: Controls log output verbosity
• Options:
• "default": Timestamp, level, and message
• "verbose": Adds module, function, and line number metadata

HAYHOOKS_INTERCEPTED_LOGGERS

• Default: ["uvicorn", "uvicorn.error", "uvicorn.access", "fastapi"]
• Description: List of stdlib loggers to intercept and route through Loguru. Only the listed loggers are patched; all others (httpx, haystack, etc.) keep their default behaviour.

HAYHOOKS_ACCESS_LOG_EXCLUDED_PATH_PREFIXES

• Default: ["/traces"]
• Description: Path prefixes for uvicorn.access request logs that should be suppressed.
• Notes:
• Useful to reduce noise from dashboard polling requests.
• Set to [] to keep all access logs.

Examples:

# Set log level
export HAYHOOKS_LOG_LEVEL=DEBUG

# Enable verbose log format (includes module:function:line)
export HAYHOOKS_LOG_FORMAT=verbose

# Also intercept haystack logs
export HAYHOOKS_INTERCEPTED_LOGGERS='["uvicorn", "uvicorn.error", "uvicorn.access", "fastapi", "haystack"]'

# Keep dashboard polling request logs
export HAYHOOKS_ACCESS_LOG_EXCLUDED_PATH_PREFIXES='[]'

OpenTelemetry (Tracing)

Hayhooks tracing relies on Haystack tracing APIs and standard OpenTelemetry configuration.

For setup walkthroughs and backend examples (SigNoz, Jaeger), see Tracing.

Install tracing extras first:

pip install "hayhooks[tracing]"

Then configure your exporter/provider using OpenTelemetry env vars (examples):

OTEL_SERVICE_NAME

• Example: hayhooks
• Description: Service name shown in your tracing backend

OTEL_EXPORTER_OTLP_ENDPOINT

• Example: http://localhost:4318
• Description: OTLP collector endpoint

Using OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

If you set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT directly for HTTP transport, use the full traces path (for example http://localhost:4318/v1/traces).

OTEL_EXPORTER_OTLP_TRACES_PROTOCOL / OTEL_EXPORTER_OTLP_PROTOCOL

• Example: http/protobuf
• Description: OTLP transport protocol (http/protobuf or grpc). If both are set, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL takes precedence for trace export.

OTEL_TRACES_SAMPLER

• Example: parentbased_traceidratio
• Description: Sampling strategy

OTEL_TRACES_SAMPLER_ARG

• Example: 1.0
• Description: Sampler argument (e.g. ratio)

HAYHOOKS_TRACING_EXCLUDED_SPANS

• Default: ["send", "receive"]
• Description: Low-level ASGI child spans to suppress from FastAPI/Starlette instrumentation. This helps keep traces readable for streaming responses by default.
• Options:
• ["send", "receive"] (default): suppress both per-chunk response send spans and request receive spans
• ["send"]: keep receive spans, suppress response send spans
• []: disable this filtering and keep all framework spans

No Hayhooks-specific OTel env vars

Hayhooks does not introduce a custom HAYHOOKS_OTEL_* exporter/provider namespace. Use standard OpenTelemetry variables for backend configuration. HAYHOOKS_TRACING_EXCLUDED_SPANS is a Hayhooks-specific instrumentation tuning setting for framework span noise, not an OpenTelemetry exporter setting.

When OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) is set, Hayhooks will also attempt an automatic OpenTelemetry bootstrap at startup using the protocol from OTEL_EXPORTER_OTLP_TRACES_PROTOCOL (falling back to OTEL_EXPORTER_OTLP_PROTOCOL) (http/protobuf default, or grpc).

Usage Examples

Docker

docker run -d \
  -e HAYHOOKS_HOST=0.0.0.0 \
  -e HAYHOOKS_PORT=1416 \
  -e HAYHOOKS_PIPELINES_DIR=/app/pipelines \
  -v "$PWD/pipelines:/app/pipelines:ro" \
  -p 1416:1416 \
  deepset/hayhooks:main

Pipeline Directory Required

Without mounting a pipelines directory (or baking pipelines into the image), the server will start but no pipelines will be deployed.

Development

export HAYHOOKS_HOST=127.0.0.1
export HAYHOOKS_PORT=1416
export HAYHOOKS_PIPELINES_DIR=./pipelines
export HAYHOOKS_LOG_LEVEL=DEBUG

hayhooks run

MCP Server startup

export HAYHOOKS_MCP_HOST=0.0.0.0
export HAYHOOKS_MCP_PORT=1417

hayhooks mcp run

.env file example

HAYHOOKS_HOST=0.0.0.0
HAYHOOKS_PORT=1416
HAYHOOKS_MCP_HOST=0.0.0.0
HAYHOOKS_MCP_PORT=1417
HAYHOOKS_PIPELINES_DIR=./pipelines
HAYHOOKS_ADDITIONAL_PYTHON_PATH=./custom_code
HAYHOOKS_USE_HTTPS=false
HAYHOOKS_DISABLE_SSL=false
HAYHOOKS_SHOW_TRACEBACKS=false
HAYHOOKS_STREAMING_COMPONENTS=all
HAYHOOKS_DEPLOY_CONCURRENCY=serialized
HAYHOOKS_STARTUP_DEPLOY_STRATEGY=parallel
HAYHOOKS_STARTUP_DEPLOY_WORKERS=4
HAYHOOKS_TRACING_ENABLED=true
# Set HAYHOOKS_TRACING_TOKEN privately, or configure verified operator authorization.
HAYHOOKS_TRACING_DEFAULT_LIMIT=25
HAYHOOKS_TRACING_MAX_LIMIT=100
# Optional: only highlight slowest components above 1s
# HAYHOOKS_TRACING_SLOW_COMPONENT_MS=1000
# Optional: exclude Haystack component spans (included by default)
# HAYHOOKS_TRACING_INCLUDE_HAYSTACK_SPANS=false
# Optional: include raw request payload values in local trace tags (safe metadata only by default)
# HAYHOOKS_TRACING_INCLUDE_PAYLOAD_VALUES=true
HAYHOOKS_CORS_ALLOW_ORIGINS=["*"]
HAYHOOKS_LOG_LEVEL=INFO
HAYHOOKS_LOG_FORMAT=default

Configuration Note

• Worker count, timeouts, and other server process settings are CLI flags (e.g., hayhooks run --workers 4 in default mode; durable mode uses replicas).
• YAML/file saving and MCP exposure are controlled per-deploy via API/CLI flags, not global env vars.

Next Steps

• Configuration
• Tracing
• Logging